During the Ask a Developer session at the Blender Conference last weekend, there was a request for easy debugging of Python code. Fortunately, with PyCharm or Eclipse/PyDev, this is quite easy. Personally I use PyCharm, but the process should be pretty similar for Eclipse/PyDev. Besides Blender and your IDE, you need more two ingredients:

  1. The egg file from your IDE. For PyCharm, this file is called “pycharm-debug-py3k.egg” and you can find it in PyCharm’s “debug-eggs” directory. Make sure you get the one for Python 3. There is no need to do anything with the file, just note down its path. On my machine, it is “/home/sybren/pycharm/debug-eggs/pycharm-debug-py3k.egg”, but yours may be in “C:\Program Files\…”
  2. My addon remote_debugger.py from GitHub.

Update 1-Nov-2015: You need the Professional version of PyCharm for this to work. Fortunately, if you can show that you actively participate in an Open Source project, you can get a Pro license for free.

Step 1: Install and configure the addon

Once you’ve downloaded remote_debugger.py, install it in Blender. Open the User Preferences window, and hit the “Install from file…” button at the bottom.

Configuring the addon

Configuring the addon

In the addon preferences, point Blender to your “pycharm-debug-py3k.egg” file. On my Linux machine it’s at /home/sybren/pycharm/debug-eggs/pycharm-debug-py3k.egg. Since you’re a developer, I’ll assume that you know where you installed your IDE.

Step 2: Create the debug server configuration

PyCharm debugger configuration

PyCharm debugger configuration

In PyCharm, create a new Python Remote Debugger configuration: Run → Edit Configurations… → + → Python Remote Debug.

Make sure Local Host Name is set to “localhost” and Port to “1090”. You can use another port number if you want, but be sure to update the addon source code to reflect this.

Step 3: Start the debug server

Starting the debug server in PyCharm

Starting the debug server in PyCharm

Start the debug server from the Run/Debug dropdown. Don’t forget to click the little bug to actually start it.

Step 4: Connect Blender

Connecting the debugger from Blender

Connecting the debugger from Blender

In Blender, hit space in the 3D viewport and search for “debugger”. Choose “Connect to remote Python debugger”. Once you do this, you will see that Blender freezes up. This is expected behaviour. Switch to PyCharm, and you’ll see that it has paused the execution of the addon just under the “pydevd.settrace(…)” call. Press the green “play” button (or press F9) to un-freeze Blender.

Step 5: Debug!

Now that everything is connected, you can debug your code like you’re used to. Set breakpoints, step through code, inspect variables, etc.

Some final words

The order in which things are set up are quite important. You only need to do steps 1-2 once, which is nice. Be sure to do steps 3 and 4 in that order, as it makes things a bit more predictable and works well.

Here are some additional links that may help with the remote debugging. You can always try to contact me (Sybren) on IRC in #blenderpython if you have questions.