Skip to main content

Interactive debugging

The goal of this page is to set up your IDE in such a way, that you will be able to start VIKTOR in debugging mode from your IDE, set breakpoints and inspect the values of variables in your code editor. Depending on your IDE, operating system and virtualization mode the instructions are different. We provide instructions for the following platforms, IDEs and virtualization modes:

Operating system:

  • Windows
  • Linux


Virtualization mode:

  • Venv
  • Docker

Configure the IDE


Before configuring the IDE for debugging, make sure you have installed your application by using viktor-cli install.

The steps for configuring your editor depend on your operating system, VIKTOR isolation mode and editor. Below instructions assume the app resides in a folder called 'my-app-folder'.

First, select your IDE and operating system:

Secondly, chose the isolation mode you use for development:

Configure the Python interpreter

In the bottom right, add a Python interpreter by clicking the Python 3.X (or <no interpreter>) button, followed by add interpreter.

Then select "existing environment", usually this is selected automatically. Then select the Python interpreter <project-name>\venv\Scripts\python.exe folder if it is not already selected. Click "ok" to save the settings.

Add existing environment

Set up debugging

Next, in the top menu, click Run > Edit configurations.

A modal will appear where you can create new debug configurations. Then follow these steps:

  1. Click the + in the top-left and from the dropdown select Python to create a new debug configuration
  2. Change Script path to Module name
  3. Type viktor_debugging in the field for the module name
  4. Select the Python interpreter you just configured
  5. Change the working directory to the project directory.
  6. (optionally) give the configuration a name, such as "VIKTOR Debug"
  7. Click OK to save the debug configuration

PyCharm should now be configured for debugging.

Set up unit tests

Go to Settings (Ctrl + Alt + S) > Tools > Python Integrated Tools.

Then under the header "Testing" change the Default test runner to Unittests (not PyTest nor Autodetect) and hit "OK" to save the changes.

Start the debugger

Before starting a debugging session, make sure that you are not running the app using the viktor-cli (close the connection using Ctrl+C). To start the debugging session, use:

  • PyCharm: In the top menu, click Run > Debug... (Alt+Shift+F9) and select the debug configuration we just made. If it is already selected you can also use Run > Debug (VIKTOR Debug) (Shift+F9).
  • Visual Studio Code: In the top menu, click Run > Start debugging... (F5).

Auto-reload is not possible in debug mode. Code changes only take effect after restarting the debugging session. (pycharm: Ctrl+F5, vscode: Ctrl+Shift+F5)

Setting breakpoints

When the debugger is started, a terminal should appear at the bottom of your editor window, in which your app is started. You should be able to go to your personal dev url in a browser and use the app. You can set breakpoints in the code, and inspect the parameters at these points.

You can read more about setting breakpoints, stepping through code and reading variables in the documentation of the specific editors:

PyCharmVS Code / Gitpod
Set breakpoints in PyCharmSet breakpoints in VS Code
Stepping through code in PyCharmStepping through code in VS Code
Reading variables in PyCharmReading variables in VS Code

When writing a Python script, normally you will hit the breakpoints when you start the script. In a VIKTOR application however, the breakpoints will only be hit when the function is triggered by the user. For example, the code in a view function runs when the view is opened in the web browser.

Note that when debugging quick views or callback functions that are used for the parametrization, the editor will not respond when the call (including debugging time) takes longer than about 10 seconds.


When debugging views, you can (temporarily) set the duration_guess to some high number to require manual triggering of the computation, leading to a nicer debug experience. This will also allow you to see the updated results in the web browser once the call is finished.

Debugging tests

We assume your tests are located in the "tests" folder.


In the project explorer, right-click a test file or test directory and then Debug "Python tests in test...".

Alternatively, you can debug individual tests (or test classes) by opening a test file and clicking the play button in the gutter and then selecting Debug "Python tests in test...".

Visual Studio Code - venv

In the left panel, choose tests (the Erlenmeyer flask icon). You should see your tests listed there. In this panel you can hover a test file and click the run or debug icon.

Alternatively, you can debug individual tests by going to your test file and right-clicking the icon in the gutter next to the test function and selecting "Debug test".

Visual Studio Code - Docker

In the left menu, go to the debug panel (Ctrl+Shift+D) and at the top choose "Unittest". Click on the green arrow next to it to debug the unit tests. This runs all unit tests.