Using Wing with NUKE and NUKEX

Index of All Documentation » How-Tos » How-Tos for Modeling, Rendering, and Compositing Systems »

Wing Pro is a Python IDE that can be used to develop, test, and debug Python code written for The Foundry's NUKE and NUKEX digital compositing tool.

If you do not already have Wing Pro installed, download it now.

This document describes how to configure Wing for NUKE and NUKEX. To get started using Wing as your Python IDE, please refer to the tutorial in Wing's Help menu or read the Quickstart Guide.

Project Configuration

First, launch Wing and create a new project from the Project menu. Although not required for working with NUKE, you may want to select your existing source directory or add it after project creation with Add Existing Directory in the Project menu. Doing this tells Wing's source analysis, search, and revision control features know which files are part of the project.

Configuring for Licensed NUKE/NUKEX

If you have NUKE or NUKEX licensed and are not using the Personal Learning Edition, then you can create a script to run NUKE's Python in terminal mode and use that as the Python Executable in Wing's Project Properties. For example on macOS create a script like this:

#!/bin/sh
/Applications/Nuke6.3v8/Nuke6.3v8.app/Nuke6.3v8 -t -i "$@"

Then perform chmod +x on this script to make it executable. On Windows, you can create a batch file like this:

@echo off
"c:\Program Files\Nuke7.0v9\Nuke7.0.exe" -t -i %*

Next, you will make the following changes in Project Properties, from the Project menu in Wing:

Set Python Executable to Command Line and then enter the full path to this script
Change Python Options under the Debug tab to Custom with a blank entry area (no options instead of -u)

Apply these changes and Wing will use NUKE's Python in its Python Shell (after restarting from its Options menu), for debugging, and for source analysis.

Configuring for Personal Learning Edition of NUKE

The above will not work in the Personal Learning Edition of NUKE because it does not support terminal mode. In that case, install a Python version that matches NUKE's Python and use that instead. You can determine the correct version to use by by looking at sys.version in NUKE's Script Editor.

Then set Python Executable in Project Properties, from the Project menu in Wing, to the full path to the Python interpreter. The correct value to use can be determined by running Python outside of Wing and executing the following:

import sys
print(sys.executable)

Using a matching Python version is a good idea to avoid confusion caused by differences in Python versions, but is not critical for Wing to function. However, Wing must be able to find some Python version or many of its features will be disabled.

Additional Project Configuration

When using Personal Learning Edition, and possibly in other cases, some additional configuration is needed to obtain auto-completion on the NUKE API also when the debugger is not connected or not paused.

The API is located inside the NUKE installation, in the plugins directory. The plugins directory (parent directory of the nuke package directory) should be added to the Python Path configured in Wing's Project Properties from the Project menu. On macOS this directory is within the NUKE application bundle, for example /Applications/Nuke6.3v8/Nuke6.3v8.app/Contents/MacOS/plugins.

Replacing the NUKE Script Editor with Wing Pro

Wing Pro can be used as a full-featured Python IDE to replace NUKE's Script Editor component. This is done by downloading and configuring NukeExternalControl.

First set up and test the client/server connection as described in the documentation for NukeExternalControl. Once this works, create a Python source file that contains the necessary client-side setup code and save this to disk.

Next, set a breakpoint in the code after the NUKE connection has been made, by clicking on the breakpoint margin on the left in Wing's editor or by clicking on the line and using Add Breakpoint in the Debug menu or the breakpoint icon in the toolbar.

Then debug the file in Wing Pro by pressing the green run icon in the toolbar or with Start/Continue in the Debug menu. After reaching the breakpoint, use the Debug Console in Wing to work interactively in that context.

You can also work on a source file in Wing's editor and evaluate selections within the file in the Debug Console with Evaluate Selection in Debug Console from the Source menu.

Both the Debug Console and Wing's editor should offer auto-completion on the NUKE API, at least while the debugger is active and paused in code that is being edited. The Source Assistant in Wing Pro provides additional information for symbols in the auto-completer, editor, and other tools in Wing.

This technique will not work in Wing Personal because it lacks the Debug Console feature. However, debugging is still possible using the alternate method described in the next section.

Debugging Python Running Under NUKE

Another way to work with Wing and NUKE is to connect Wing directly to the Python instance running under NUKE. In order to do this, you need to import a special module in your code, as follows:

import wingdbstub

You will need to copy wingdbstub.py out of the install directory listed in Wing's About box and may need to set WINGHOME inside wingdbstub.py to the location where Wing is installed if this value is not already set by the Wing installer. On macOS, WINGHOME should be set to the full path of Wing's .app folder.

Before debugging will work within NUKE, you must also set the kEmbedded flag inside wingdbstub.py to 1.

Next click on the bug icon in the lower left of Wing's main window and make sure that Accept Debug Connections is checked.

Then execute the code that imports the debugger. For example, right click on one of NUKE's tool tabs and select Script Editor. Then in the bottom panel of the Script Editor enter import wingstub and press the Run button in NUKE's Script Editor tool area. You should see the bug icon in the lower left of Wing's window turn green, indicating that the debugger is connected.

If the import fails to find the module, you may need to add to the Python Path as follows:

import sys
sys.path.append("/path/to/wingdbstub")
import wingdbstub

After that, breakpoints set in Python modules should be reached and Wing's debugger can be used to inspect, step through code, and try out new code in the live runtime. Breakpoints set in the script itself won't be hit, though, due to how Nuke loads the script, so code to be debugged should be put in modules that are imported.

For example, place the following code in a module named testnuke.py that is located in the same directory as wingdbstub.py or anywhere on the sys.path used by NUKE:

def wingtest():
  import nuke
  nuke.createNode('Blur')

Then set a breakpoint on the line import nuke by clicking in the breakpoint margin to the left, in Wing's editor.

Next enter the following and press the Run button in NUKE's Script Editor, just as you did when importing wingdbstub above:

import testnuke
testnuke.wingtest()

As soon as the second line is executed, Wing should reach the breakpoint. Then try looking around with the Stack Data and Debug Console (in Wing Pro only).

Debugger Configuration Detail

If the debugger import is placed into a script file, you may also want to call Ensure on the debugger, which will make sure that the debugger is active and connected:

import wingdbstub
wingdbstub.Ensure()

This way it will work even after the Stop icon has been pressed in Wing, or if Wing is restarted or the debugger connection is lost for any other reason.

For additional details on configuring the debugger see Debugging Externally Launched Code.

Limitations and Notes

When Wing's debugger is connected directly to NUKE and at a breakpoint or exception, NUKE's GUI will become unresponsive because NUKE scripts are run in a way that prevents the main GUI loop from continuing while the script is paused by the debugger. To regain access to the GUI, continue the paused script or disconnect from the debug process with the Stop icon in Wing's toolbar.

NUKE will also not update its UI to reflect changes made when stepping through a script or otherwise executing code line by line. For example, typing import nuke; nuke.createNode('Blur') in the Debug Console will cause creation of a node but NUKE's GUI will not update until the script is continued.

When the NUKE debug process is connected to the IDE but not paused, setting a breakpoint in Wing will display the breakpoint as a red line rather than a red dot during the time where it has not yet been confirmed by the debugger. This can be any length of time, if NUKE is not executing any Python code. Once Python code is executed, the breakpoint should be confirmed and will be reached. This delay in confirming the breakpoint does not occur if the breakpoint is set while the debug process is already paused, or before the debug connection is made.

These problems should only occur when Wing's debugger is attached directly to NUKE, and can be avoided by working through NukeExternalControl instead, as described in the first part of this document.

Wing Python IDE

The Intelligent Development Environment for Python

Navigation