Debugging python code IN nuke with Eclipse (step through like a pro!)

Written by Jordan Olson on .


This tutorial is intended for technical artists or developers who already know how to run Python scripts in Nuke.

What is debugging? If you already know, skip on ahead.

Debugging offers you the ability to pause code execution and interact with a live session. Most debuggers allow you to run commands, view variables, and step (run) through lines of code one at a time. They allow you to view the call "stack". (e.g. which methods have called which methods).

Some even allow you to change variables or import modules in the middle of code execution, and to view the call stack, (e.g. which methods have called which methods). PyDev for Eclipse IDE supports all of the above, and as open source it's free to download and use!


Local debugging Python scripts with Eclipse

At my last studio Eclipse was our IDE of choice and we used it for all of our python writing needs. You'll need Eclipse installed with the PyDev plugin.

Running the active python script in debug mode is straightforward. Press F11 on your keyboard or the bug button : 


In a nutshell, this is how it works. F11 in your keyboard runs the current script- in debugging mode. It will pause at the breakpoints you set. You can set breakpoints by double clicking on the margin to the left of line numbers. For example, double click on the grey space just to the left of the number 13 in your editor to tell the program (debugger) to pause when it reaches that line. When it has paused, you have access to shortcuts to work through the action; F5 will step into any function/method calls, F6 will move simply to the next line after executing the current line, F7 will finish executing the current function/clause and step out/return to the host call, and finally F8 will resume running as normal until the debugger finds another breakpoint. When the debugger is paused, you can run commmands in the Console (cool!) and view/change variables in the Variables window.

For a more detailed breakdown, check out this page. 


Remote debugging another application or computer

Now the fun begins. This is how we can debug our scripts IN Nuke from Eclipse. We can view the modules in memory (including nuke) and read stdout text returned from Nuke.

First you you need to be in Debug Perspective. If the button isn't there as it is in the screenshot, you'll need to use Window > Open Perspective > Other to find the PyDev debug perspective.

Secondly you'll need to have a debug server running, which you can access as indicated above. 

The debug server will listen for any scripts attempting to connect to it, and once the connection is made, you're in control of the session from Eclipse regardless of where the script is running, be it on your machine, in another program, or even on another computer. The only catch is the file-path needs to be the same- so debugging on another machine takes extra care.

Now the script you wish to debug must have access to the pydevd module which comes with PyDev. This is how I set up the path on my computer. This goes into the top of the script I want to step through in Nuke. This path will vary depending on your version, so don't just copy-paste what I've got here.

import sys

Alternatively you can copy the folder into your PYTHONPATH.  By appending the path into the sys module, I have given this python session (only) the ability to import pydevd, which it needs to communicate with the debug server.

import pydevd

Next, the settrace() method is what connects the script to the debugger server. 

Best yet- with Nuke- you can tell the python script to send text and errors to the Eclipse console. Note these optional arguments in settrace().

pydevd.settrace(stdoutToServer=True, stderrToServer=True, suspend=False)

In this screenshot I've imported a script in Nuke which has triggered Eclipse to stop at the highlighted line. Now I can inspect the nuke module, send commands to Nuke via the Console, view variables, and step through code. 

Finally, you can also debug a script over the local area network (LAN) running on another machine by specifying an IP address.

pydevd.settrace('', stdoutToServer=True, stderrToServer=True, suspend=False)

Might come in handy next time that comper has a bug you can't replicate?

Important notes

Debugging does not work well with Threads- if you're running python Threads or QThreads in your application, debugging can be tricky. I recommend making an additional method to permit non-threaded operation as a backup for ease of debugging.

Here is an example of how I've done so in one python Qt application.

Threaded Class declaration

class Interface(QThread):
   def __init__(self, **kwargs):
   def non_threaded_run(self):
       # by not calling QThread.start() we bypass Qt's thread creation methods
   def run(self):
       # this method is called by the QThread.start() method which creates a thread
       self.action = pipeline.action('AutomaticCompAction')


After asking colleagues if they knew how to debug in Maya or Nuke, I was surprised to find that few TDs actually were aware of how to debug in the first place! Coming from a background of Mel and PyMel in Maya, most of the technical developers I worked with just were unaware of this time-saving technique. So after running a training session, this tutorial is my attempt to help other TDs have an easier time developing code for Nuke.


+2 # Jordan Olson 2013-10-16 23:05
If you have any questions or comments, be sure to post them and I'll take a look.
+1 # Alex Gamaiunov 2013-11-01 07:30
I'm writing some tools for colleagues and myself for a few years now and always want to find a better way to debug this procces.
I didn't quite understood your way of setup and wanted (if you have time) to talk to you one-on-one.

Is it possible?
0 # Jordan Olson 2013-11-02 01:47
Sure Alex, hit me up- jorxster (at) and I'd be happy to chat.
+2 # Da Go 2013-11-04 10:58
Thx! Finally debugging with NUKE and Eclipse.

But its not working with PyDev version > 2.8 !!
I uninstalled PyDev in Eclipse and copied manually PyDev 2.8 into Eclipse. Now is working again! :)
0 # Jordan Olson 2014-02-11 05:45
Good to know!
I haven't updated either eclipse or nuke in a while, but I imagine you'd need the python versions to match as well.
0 # Timur Khodzhaev 2014-02-10 22:21
Hi, Jordan.

thank you for a tutorial.
I have some troubles trying to go through it. Could you help me figure out what am I doing wrong, please?

I installed eclipse and pydev plugin.
then Im importing sys and adding path
import pydevd working fine
and then when Im trying to settrace

pydevd.settrace (stdoutToServer =True, stderrToServer= True, suspend=False)

Im getting this error message:

Traceback (most recent call last):
File "", line 2, in
File "/opt/eclipse/p lugins/org.pyth on.pydev_3.3.3. 201401272249/py src/", line 1510, in settrace
_locked_settrac e(host, stdoutToServer, stderrToServer, port, suspend, trace_only_curr ent_thread)
File "/opt/eclipse/p lugins/org.pyth on.pydev_3.3.3. 201401272249/py src/", line 1531, in _locked_settrac e
debugger.connec t(host, port) # Note: connect can raise error.
File "/opt/eclipse/p lugins/org.pyth on.pydev_3.3.3. 201401272249/py src/", line 381, in connect
s = StartClient(hos t, port)
File "/opt/eclipse/p lugins/org.pyth on.pydev_3.3.3. 201401272249/py src/pydevd_comm .py", line 397, in StartClient
s.connect((host , port))
File "", line 1, in connect
socket.error: [Errno 111] Connection refused

Is that something like wrong version of python or plugin using other version of python rather then my system?
I think I have python 2.6 on my system.

many thanks
0 # Jordan Olson 2014-02-11 05:44
Hi Tim,

From what I can see, you're importing pydevd from Python 3.3,
e.g. ...."plugins/or g.pyth on.pydev_3.3.3. 201401272249/..."

Note the pydev_3.3.3 string, I believe this version represents the version of python. Now if there is any such case that python is incompatible.. it's between 2 and 3!

On my machine I've got 2.7 (and in the tutorial)

How to fix? I went to PyDev's website; looks like you'll have to dig around to get an older version of PyDev as their recommended installation just comes with LiClipse now.

Or you could try debugging a python 3.3 session- but note that Nuke comes with 2.X...

Hope that helps.
0 # Timur Khodzhaev 2014-02-11 18:57
oh sorry that was my fault.
Figured out that I didnt started the server thats why it was unable to connect...
stupid mistake...

+1 # Da Go 2015-01-19 15:58
Hello guys,

With the Nuke9 is PyDev3.9 now working too! :)


You have no rights to post comments

We have 2620 guests and 50 members online