PyCharm setup for add-on debugging

I thought I would share my current workflow for add-on development in PyCharm. It admittedly feels like a bit of a ‘hack’, so I would warmly welcome any comments/criticisms from more experienced developers. But hopefully it will help a few people out.

My main goals were as follows:

  • Be able to launch Anki from within PyCharm
  • Run in debug mode so I could see print statement outputs and place breakpoints in both my own add-on code and the Anki source code (eg. to see within Anki how variables are set, the flow between functions, etc.)

I had a lot of head-scratching to get a process working since the switch to the Bazel build system. I still have not been able to actually launch Anki within PyCharm from the downloaded source code, only from pre-built wheels as shown below.

Project structure

This isn’t strictly necessary, but I use the following project structure prescribed by anki-addon-builder:anki-addon-builder

└── (copied from anki source; used to run in Pycharm)
└── addon.json [required only for aab]
└── src
    └── {my_addon_name}
 			   ├── project files (, etc.)

A key here is the file. This is what allows Anki to be launched from within the PyCharm project. I copied the file directly from the Anki source code, but its contents are as follows:

#!/usr/bin/env python3
# Copyright: Ankitects Pty Ltd and contributors
# License: GNU AGPL, version 3 or later;

import os
import sys

    import bazelfixes

except ImportError:

import aqt

if not os.environ.get("ANKI_IMPORT_ONLY"):

Virtual environment setup

Create a virtual environment and install anki and aqt. You can either build wheels from the source code (as detailed in the documentation) or download the current versions from PyPI. This can be done on the command line, but a simpler method within PyCharm is detailed below.

Open up the root folder of the project in PyCharm. Open the PyCharm Preferences dialog and select Project > Python Interpreter on the sidebar. In the ‘Python Interpreter’ dropdown, select ‘Show All…’, then click the ‘Add’ button to create a new virtual environment.

Insert any desired location for the virtual environment and select the Python interpreter (ideally, it should match the Python version used in the latest Anki build).

Now, click the ‘+’ button to install the aqt and anki packages.

Run configuration

Add a new run/debug configuration. For the Script Path, select the file in the project directory. Python Interpreter should be Python in the project’s virtual environment.

If you want to automatically load a certain Anki profile (eg. a separate one for development), you can add -p Development_profile_name to the Parameters field.

Running Anki in debug mode

If you click the debug (or run) button in the upper right of the window, it should now launch Anki. The add-on itself won’t be available to Anki yet, but we’ll fix that shortly (see below).

You can find the anki source files in the packages under External Libraries in the sidebar. You can place breakpoints in any file to pause execution (eg. to examine the values of variables or to step through the code execution).

Activating the add-on

The add-on directory needs to be within the Anki add-ons directory in order for it to be loaded. This can be done by creating an alias. On the Mac, a regular alias won’t work and you have to create a symlink using the Terminal as follows:

ln -s "/{PATH TO PROJECT DIR}/my_addon/src/my_addon" \

Note that only the my_addon directory within the src directory is symlinked, not the root project directory. Replace the curly bracket components, and whatever the symlink folder is named will be displayed as the add-on name in Anki.

After launching Anki, check to make sure that the add-on is active using the usual Add-ons menu item.

Now, you can add breakpoints to your add-on code and see print statements in the console.

Suppressing the Import window

For some reason, when you launch Anki in debug mode (not run mode), it will always show the Import window on startup.

You can suppress this by making a change to the aqt/ file. Of course, you shouldn’t really edit files in the libraries in this way (and PyCharm will show a warning), so look at this as a bit of a hack.

In the file aqt/, find the function def onAppMsg(self, buf: str). Near the end of the function, you will see the following:

# import / add-on installation
if is_addon:

Comment out the line self.handleImport(buf) and replace it with pass:

# import / add-on installation
if is_addon:
    # self.handleImport(buf)

This should stop the Import window from displaying on startup.


Thank you for this contribution.

I have used this gracious resource to help create a tutorial on YouTube explaining this process.

1 Like