PyCharm 2023.1 Help

Run and debug Jupyter notebook code cells

You can execute the code of notebook cells in many ways using the icons on the notebook toolbar and cell toolbars, commands of the code cell context menu (right-click the code cell to open it), and the Run commands of the main menu. Note that when you work with local notebooks, you don’t need to launch any Jupyter server in advance: just execute any cell and the server will be launched.

Run code cells

  • Use the following smart shortcuts to quickly run the code cells:

    • Control+Enter: Runs the current cell.

    • Shift+Enter: Runs the current cell and selects the cell below it.

    When executing one cell at a time, mind code dependencies. If a cell relies on some code in another cell, that cell should be executed first.

    When the execution is done, the cell remains in the edit mode, so that you can modify it, if needed, and keep experimenting.

    In the lower left corner of the cell, you can find the information about the last cell execution. It includes the execution duration, as well as the date and time when the execution finished.

    The information about the last cell execution

    In case of any errors, expand the Traceback node to view the complete error message.

    Error traceback
  • To execute all code cells in your notebook, click Run all on the notebook toolbar or press Control+Alt+Shift+Enter.

When you stop the server and change the server or kernel, you have to execute all cells with dependencies again, because execution results are valid for the current server session only.

View variables

Jupyter Variables tool window

  • When you execute your notebook, you can preview variables in the Variables tab of the Jupyter tool window .

    Jupyter server tool window: the Variables tab

    By default, variables are loaded asynchronously. To change the loading policy, click Manage the loading policy in the Variables tab, select Variables Loading Policy, and select one of the available modes. See Managing Variables Loading Policy for more details.

    You can click the link to the right of the variable to preview its values in the tabular form.

Data Vision

In addition to watching the values of variables in the Variables tab, you can preview them in the editor.

  1. Go to Settings | Languages & Frameworks | Jupyter and make sure that the Show inline values in editor checkbox is enabled.

  2. Run the notebook cell. The values of variables are shown next to their usages:

    Inline variables in the source editor

Work with outputs

Once you’ve executed the cell, its output is shown below the code. You can save the results or clear the output.

Plots

  • If your notebook cell involves any code that plots charts, you can save the chart as an image: right-click the output and select Save As from the context menu.

  • If you are using a dark UI theme, the colors in charts are adapted for better readability by default. To change this behavior, disable the Invert image outputs for dark themes checkbox on the Languages & Frameworks | Jupyter page of the IDE Settings (Control+Alt+S) and restart the editor to apply the changes.

  • You can resize the plots in output cells. To do that, move the mouse pointer to the bottom of the cell, so that the pointer becomes a double arrow. Then click and drag the cell border up or down to reach the desired size:

Tables

  • When data frames are built, they are displayed in the tabular form. To open a data frame in a separate editor tab, click Open In New Tab in the upper-right corner of the output cell.

    Open cell output in a new tab

    Right-click the column name to open the context menu:

    Copying table headers
    • To copy the column name to the clipboard, select Copy Column Name.

    • To hide a column, select Hide Column. Hide Other Columns will hide all columns except the selected one.

    • To display hidden columns, click Columns List Control+F12. The hidden columns are shown strikethrough. Select a column and press Space to toggle its visibility. To search through the column list, start typing a column name in the Columns List window.

    • To sort the table data based on the column values, you can either click the column name or select Ascending or Descending from the context menu.

    • To assign a language to a column, use Set Highlighting Language. For more information, see Inject a language for a column.

  • You can browse table data in several modes: Table, Tree, Text, and Transpose. To switch between these modes, click the View as button in the upper-right corner of the output cell and select the mode that you need.

    Switching between viewing modes

    For more information about viewing modes, see View data.

    To configure the way PyCharm displays data in the Text mode, use the Data Extractors drop-down:

    Py ds tables data extractors

    For more information, see Data extractors.

You can manage the length of the notebook by expanding and collapsing cell outputs. Click an arrow nearby a cell counter to expand or collapse the cell output.

Preview reference documentation

With PyCharm you can always quickly preview reference documentation for a particular variable, type, or argument.

  1. To view reference information for any element of a particular code cell, place the caret within the target code cell and type ? <type/variable/argument>. (in this example, you will preview documentation for plt.scatter). Note that a code element should be accessible within the code cell.

  2. Execute the cell. The Introspection tab opens in the Jupyter tool window.

    Previewing reference documentation for plt.scatter
  3. Preview reference documentation in the Introspection tab.

Note that the Introspection tab shows documentation for the latest requested code element. Even though you proceed with executing other code cells, restart the server, or delete the line with your request, this information will be shown.

PyCharm provides the full-functional Jupyter Notebook Debugger for both local and remote Jupyter server kernels.

Debug code in Jupyter notebooks

  1. Set the breakpoints in the selected cell and press Alt + Shift + Enter for Windows or ⌥⇧↩ for macOS. Alternatively, you can right-click the cell and select Debug Cell from the context menu.

    The Jupyter Notebook Debugger tool window opens.

    Jupyter Notebook Debugger tool window
  2. Use the stepping toolbar buttons stepping toolbar to choose on which line you want to stop next and switch to the Debugger tab to preview the variable values:

    Stepping over in the Jupyter Notebook Debugger

    Debugging is performed within a single code cell. However, if your code cell calls a function from any cell that has been already debugged, you can step into it. The related breakpoints will also work. Note that the cell with the function must be debugged not just executed.

    Similarly, you can step into a function called from a Python file that is located in the same project.

  3. Proceed with the debugging steps to complete the execution of the cell.

    Debugging is complete

Stepping actions

Item

Tooltip and Shortcut

Description

Action available on the Debugger toolbar.

Step over

Step Over

F8

Click this button to execute the program until the next line in the current method or file, skipping the methods referenced at the current execution point (if any). If the current line is the last one in the method, execution steps to the line executed right after this method.

Step into

Step Into

F7

Click this button to have the debugger step into the method called at the current execution point.

Step out

Step Out

Shift+F8

Click this button to have the debugger step out of the current method, to the line executed right after it.

Additional stepping actions available by clicking More stepping actions on the Debugger toolbar.

Force Step Over

Force Step Over

Steps over the current line of code and takes you to the next line even if the highlighted line has method calls in it. If there are breakpoints in the called methods, they are ignored.

Smart Step Into

Smart Step Into

Smart step into is helpful when there are several method calls on a line, and you want to be specific about which method to enter. This feature allows you to select the method call you are interested in.

Run to cursor

Run to Cursor

Alt+F9

Click this button to resume program execution and pause until the execution point reaches the line at the current cursor location in the editor. No breakpoint is required. Actually, there is a temporary breakpoint set for the current line at the caret, which is removed once program execution is paused. Thus, if the caret is positioned at the line which has already been executed, the program will be just resumed for further execution, because there is no way to roll back to previous breakpoints. This action is especially useful when you have stepped deep into the methods sequence and need to step out of several methods at once.

If there are breakpoints set for the lines that should be executed before bringing you to the specified line, the debugger will pause at the first encountered breakpoint.

Force Run to Cursor

Force Run to Cursor

Continues the execution until the position of the caret is reached. All breakpoints on the way are ignored.

Last modified: 21 June 2023