Many people use the standard Python debugger (pdb or ipdb) because it works well and can be used as a standalone tool or with your favorite editor. I’ve used it for years, but today I’m more productive using the PyCharm debugger. It can debug Python, JavaScript, and Django and Jinja Templates (making the debugging process seamless in web applications). Also, I don’t have to worry about leaving pdb.set_trace calls around anymore.

Since the process to run and debug code in PyCharm is similar, we will look how to run code first (jump to the debugging section if you already know how to run code in PyCharm).

In this article shortcuts are written with the first letter of keyboard modifiers followed by the actual keys in lower case. The keys are presented for both OS X and Windows/Linux in the format (mac, win). For example, the shortcut (⌘-S-⌥-t, S-A-C-t) means to press the keys ⌘, Shift, Option, and t at the same time on the Mac, and Shift, Alt, Control, and t on Windows and Linux. When only one shortcut is presented, it will be the same on all operating systems.

Running Python Code

If we haven’t run any code in our project before, the icons to run and debug will be disabled:

Some items will be disabled in the Run menu as well:

To run a script for the first time, we need to either create a configuration (Run→Edit Configurations…) or ask PyCharm to run the current file by going to Run→Run… (⌥-C-r, A-C-r), where PyCharm will automatically offer to run the current file. In the following example I’m editing a file named Notice how PyCharm creates a new configuration named analysis:

PyCharm will run the file and show a tool window with the results, if any.

The Run tool window has many buttons to help us deal with the running script. We can do things like pause, stop, and rerun the script and move up and down the stack trace.

The following table summarizes the main actions. The manual has a complete description.

Name Shortcut Description
Rerun `(⌘-r, C-F5)` Stop the current process and run it again
Stop `(⌘-F2, C-F2)` Stop the current process
Pause Output Keep running the process but don’t show its output
Restore Layout Restore the default window layout, discarding the current one
Pin Tab Run code on a new tab
Close `(⌘-w, S-C-F4)` Closes the current tab and terminate the process
Up the stack trace `(⌘-⌥-↑, A-C-↑)` Navigate up the stack trace
Down the stack trace `(⌘-⌥-↓, A-C-↓)` Navigate down the stack trace
Use Soft Wraps Enable word wrap for long lines
Clear All Remove all text in the console

We can hide the Run tool window with (⌘-4, A-4).

Once a script is run for the first time, it becomes available in the Run menu. PyCharm will show the most recently run command in Run→Run '<script name>' (C-r, S-F10), where <script name> is the name of the Python file without the extension (analysis, in our previous example).

This command will run the original file even if we are working on a different one. In our example, if we are editing a different file (say and type C-r on the Mac or S-F10 on Windows or Linux, PyCharm will run the file, since this is the last file we ran. This is useful when we have a master script and are making modifications to a sub-module, for instance.

After we run the script for the first time, the related commands in the menubar will be available, and we can choose the script to run there:

PyCharm will create a new tab every time we run a script. If we don’t close the previous tab we may end up with many different tabs, so make sure you close each tab after running, and are, in fact, on the right tab.

New Configuration

When we want to run things with more control we need to create a configuration by going to Run→Edit Configurations… and clicking on the + button (⌘-n, A-Insert). PyCharm will ask what type of configuration we want (that is, if we want to run a Python script, a Django or Pyramid server, and so on) and will show the appropriate options for each type.

We can choose the script to run, passing parameters if necessary, the Python interpreter, and the working directory. We can also launch an external tool before running the script, which is great if we need to do things like data pre-processing.

In the Logs tab we can add log files to be shown in PyCharm’s console during the script execution or save the console output to a file.

Naturally, we can have multiple configurations; we can switch between them by going to Run→Run… (⌥-C-r, A-C-r) and picking the one we want.

The Python Debugger

To debug code in PyCharm, we need to create a new configuration in Run→Edit Configurations… or debug an existing script by going to Run→Debug… (⌥-C-d, S-A-F9). After that it will be available in Run→Debug '<script name>' (C-d, S-F9), where <script name> is the name of the Python file without the extension (analysis, in our example). As you can see, it works just like running code.

Similarly to the Run command, the menubar will now be enabled and we can choose the script to debug by clicking on the insect icon.

One of the main differences between running and debugging a script is that in debugging we want to define breakpoints. In PyCharm, a breakpoint must be on a line with working code; it can’t be on a line that is blank or starts with a comment. We create breakpoints by clicking on the gutter on the left.

We can also create a temporary breakpoint by Alt-clicking on the gutter. As the name suggests, a temporary breakpoint will be removed after being hit. Notice that the temporary breakpoint icon is different from the regular one. Check the manual for more information about breakpoint icons.

PyCharm’s debug tool window has everything we expect in a graphical debugger. From here we can navigate the call stack and inspect the data available in each stack frame. We can keep an eye on some variables by adding them to the watch list.

The debug tool window has many of the buttons we have seen in the Run tool window, allowing us to pause, stop, and rerun the script. In addition, we can view the breakpoints—also available in Run→View Breakpoints… (⌘-S-F8, S-C-F8)—and mute (that is, disable) all breakpoints.

The icons in the top right corner, allowing us to step in and out of the program, are the ones we will use the most:

In the following image, we can see each icon with its name. The table below shows the name, shortcut, and description for each icon.

Name Shortcut Description
Show Execution Point `(⌥-F10, A-F10)` Go back to the execution point. Useful if we visit other files and want to go back
Step Over `(F8)` Step to the next line
Step Into `(F7)` Descend into a method or function call on the next line
Force Step Into `(S-⌥-F7, S-A-F7)` Descend into the method even if it’s to be skipped
Step Out `(S-F8)` Return to the line where the current function was called
Run to Cursor `(⌥-F9, A-F9)` Run the code where the caret is located. Useful to skip stepping over uninteresting code
Evaluate Expression `(⌥-F8, A-F8)` Evaluate an expression or code fragment

The variables pane is a great way to explore complex data. It was invaluable when I was learning Django and getting acquainted with the HttpRequest object, for instance. In the following example, we can see some music21 data, especially the complex Score class. The Variables pane helps me to inspect attributes such as duration and elements.

We can see all breakpoints in Run→View Breakpoints… (⌘-S-F8, S-C-F8). From here we can add, remove, or edit breakpoints; and set conditional breakpoints and log messages or expressions.

One way to quickly edit a breakpoint is to right-click on the breakpoint on the gutter. A popup will allow us to enable the breakpoint and add a condition.

We can also see the breakpoints by selecting the Favorites Tool (⌘-2, A-2).

A quick way to disable a breakpoint is by clicking on it with the Alt key. The breakpoint icon will change.

Another way to disable a breakpoint is by right-clicking on it and unchecking the first option (“Line 93 in enabled” in the following example).

Besides defining breakpoints when a line of code is reached, we can define a breakpoint that is triggered when an exception is thrown. To add an exception breakpoint, we go to Run→View Breakpoints… (⌘-S-F8, S-C-F8) and select Python Exception Breakpoint after clicking the + button.

We need to include the exception class by searching for its name. The search field works with both built-in and custom exception classes.

Our new exception now appears on the list, where we can customize it.

In most cases, we want to activate the breakpoint when the exception is raised (the default is to activate the breakpoint when the exception terminates):

Having configured an exception breakpoint, PyCharm will create the breakpoint automatically when the exception is raised (ChoralException, in our example). Notice that the exception breakpoint icon is different from the regular one.

Python Prompt

Sometimes it’s useful to be able to access a Python prompt while debugging. We can do this by clicking on the Console tab when the debugger is running and selecting the Show Python Prompt icon.

Now we can use the prompt to inspect and change the variables in the current scope.

Evaluating Expressions

Although it’s super-useful to have a full Python prompt available while debugging, the Evaluate Expression feature may be sufficient if we just want to quickly evaluate an expression.

As expected, we can use any variable in the current scope:

If we select the Code Fragment Mode button, we can add multiple lines of code. Completion works here as usual.

Inspecting and Watching Variables

The fastest way to inspect the value of variables while debugging is by hovering the cursor over a variable name. PyCharm will show the variable name and its value.

And, as expected, we can inspect and set a variable value by choosing the correct option in the popup menu on the Variables pane.

The same apply to watched variables; we can edit and inspect them by using the popup menu.

Remote Debugging

PyCharm has support to debug code remotely. Probably, the most popular and useful way is to debug code in a Vagrant box.


PyCharm has a debugger that is second to none. If you want to learn more about PyCharm and how to use it to debug JavaScript and Django templates, check my ebook, Modern Python Development with PyCharm.