Web Analytics Made Easy - Statcounter
Skip to content

The Debugger

Debugger call reference

A unique feature of PySimpleGUI is a built-in "Debugger". It's not an IDE or a way for you to set breakpoints, but rather it's a way to see values of variables and use a "Real-time REPL". This feature was added in 2019 with most users perhaps not realizing it's available nor how to use it.

This feature is currently only available in the tkinter port of PySimpleGUI.

Your Code Never Stops

Unlike traditional debuggers where you set a breakpoint and stop your program while you examine variables, the PySimpleGUI debugger runs in parallel with your program. The advantage to this is that you can watch your program's variables change in real-time.

The Debugger Windows

There are 2 windows that make up the debugger.

  • Popout Window - mini window that shows local variables
  • Main Debugger Window - shows variables, has live REPL, and other features

Popout Window

popout

Main Debugger Window

main debuggger

Displaying The Debugger Windows

There are 2 ways to display the Debugger Windows:

  1. Use your keyboard
  2. Call one of the show debugger windows functions

If you would like an alternate key-binding for the window display, then create a new binding and call the display function from within your event look.

Displaying The Popout Debugger Window

There are 3 ways to get the popup window to display.

  1. Use your keyboard - press the Break key
  2. Call show_debugger_popout_window()
  3. From the Main Debugger Window, click the "Popout" button

The default location for the popout window is the upper right corner of your primary display. You can change the location of the popout if you call the function to show the window.

Displaying The Main Debugger Window

There are 3 ways to get the popup window to display.

  1. Use your keyboard - press Control + Break keys
  2. Call show_debugger_window()
  3. From the popout window, right click and choose "Debugger" from the right-click menu

You can change the location of the Debugger Main Window if you call the function to show the window.

A Sample Program

Now that you understand what the debugger is, let's make a simple little program that we can use to see the features of the debugger in action.

import PySimpleGUI as sg

layout = [  [sg.Text('My Window')],
            [sg.Input(key='-IN-')],
            [sg.Text(key='-OUT-')],
            [sg.Button('Go'), sg.Button('Exit')]  ]

window = sg.Window('Window Title', layout)

counter = 0
while True:             # Event Loop
    event, values = window.read(timeout=200)
    if event == sg.WIN_CLOSED or event == 'Exit':
        break
    counter += 1
    window['-OUT-'].update(counter)
window.close()

Using the Popout Window

While the program is running, pressing the Break key shows us this window. Notice that the variable counter is changing in real-time.

Also notice that the values dictionary is changing as characters are typed into the Input Element.


Using the Main Debugger Window

The Main Debugger Window has 2 tabs. One is for "watching" variables and dumping out the locals and globals. The other has the "Live REPL" that enables you to type in and run code, change variables, etc.


choose watches

locals

globals

REPL & Watches Tab

The REPL & Watches tab contains the "Live REPL" prompt. The Live REPL allows you to entire code much like the REPL prompt when running Python. The difference is that your program is continuing to run in the background.

As you can see from the example below, you can view variables, view the contents of variables that are objects and modify variables. In this example the counter is being reset to 0. The variable window is a Window object. By clicking the "Obj" button you can view the contents of the object.


Implementation Details

The way the debugger windows are updated is that when you call window.read() PySimpleGUI will refresh the debugger windows. Thus, it's important you call read periodically.

As a side effect from this behavior, when you have debugger windows open, you will see timeout events being returned from window.read() even if you don't have any timeout value specified. It's a side effect that should have no impact on your program if you've structured your event loop to look for events you are expecting and ignore all other events.

Disabling

To disable the debugger, set the parameter debugger_enabled=False when creating your window.