Hiero/Nuke Studio to Shotgun API Example


In this example we will install the Shotgun API using the Python 3 interpreter that is shipped with Nuke

To install the Shotgun API:

  1. Open a Command Prompt or Terminal and navigate to the following directory depending on the OS you’re using.

  • Mac:

    /Applications/Nuke<nuke version>/Nuke<nuke version>.app/Contents/MacOS/
  • Windows:

    c:\Program Files\Nuke<nuke version>\
  • Linux:

    /usr/local/Nuke<nuke version>/
  1. Next, install the Shotgun API using pip

  • Mac and Linux:

    ./python3 -m pip install --user git+git://github.com/shotgunsoftware/python-api.git
  • Windows:

    python.exe -m pip install --user git+git://github.com/shotgunsoftware/python-api.git
  1. After the installed completes, enter:

  • Mac and Linux:

  • Windows:



    On Mac and Linux, for versions of Nuke earlier than Nuke13.x, use ./python2 instead of ./python3

  1. And then inside the interpreter enter:

    import shotgun_api3

If no errors are displayed, the API is installed correctly.

To install the FoundrySG tools:

  1. Create the following directory by OS, if it doesn’t exist:

    • Windows: C:\Users\{username}\.nuke\Python\Startup

    • Mac: /Users/{username}/.nuke/Python/Startup

    • Linux: /home/{username}/.nuke/Python/Startup

  2. Copy the foundrySG_Example.py example into the correct directory by OS.

  3. Open foundrySG_Example.py in a text editor.

  4. Replace sgURL, sgLogin, and sgPassword with your Shotgun credentials.

  5. Update the ffmpeg variable in foundrySG_Example.py to point to the location of your ffmpeg installation. If you don’t already have ffmpeg installed you will need to install it.

  6. Update the projectName variable to match the project you will be working on.


Make sure the login credentials used have managerial permissions in Shotgun.

When you next start Hiero or Nuke Studio you should see the FoundrySG menu in the top menu bar.

Foundry Shotgun Methods

On startup the Foundry to Shotgun toolset menu is visible as FoundrySG:


In order for FoundrySG example to work, all shots must follow a particular naming convention, which is:

<sequence><shot number>_<task>_v<three digit version number>.<frame number beginning at 1001>.<extension>

For example: tst0020_comp_v001.1001.jpg

In the example above, the sequence is ‘tst’, the shot number is ‘0020’, the task is ‘comp’, and the three digit version number is 001. You can adjust the length of the sequence name by setting the seqChars variable in the example script (the default is 3 characters long).

The following functions are supported:

Set Clips task colors

Takes your selected clips and for each of them matches the task token eg. tst0020_**comp**_v001 against the list in the foundrySG_Example.py file. If it finds a match, it colors it accordingly. In order for this to work you will need to update the taskListColours near the top of the script such that it contains a key/value pair where the key is the department token and the value is the desired color.

For example: taskListColours.update( {‘plates’: [120,120,120]} )

Publish selected Clips

Publishes selected clips to Shotgun by making a movie of each and checking if the project exists on SG. The example then checks these exist and creates them if necessary:

Sequence Shot Task Version

The movie files are then uploaded against the correct Version.

Pull Clips Statuses from Shotgun

Tries to find the corresponding Shotgun versions to match the local clips. If successful it then pulls the SG shot/task status and applies the corresponding equivalent to each clip.

Push Clips Statuses to Shotgun

Takes the status tags applied to clips on the timeline, tries to find an equivalent for Shotgun and updates the shot/task on SG.

Push Selected Clips to new Shotgun Playlist

Takes the status tags applied to clips on the timeline, tries to find an equivalent for Shotgun and updates the shot/task on SG. There are only a limited number of status’ available in Shotgun, if the tag you’ve set on your clip does not match any of the status’ available in Shotgun, the push will do nothing.

Pull Shotgun Playlist clips to the bottom track

Requests the name of a valid and existing SG Playlist, queries it and attempts to load the corresponding footage placing it in it’s own bin in the NukeStudio project. It then places the clips in order on the lowest track. Be sure to have a clear track at the very bottom of the current sequence, otherwise it will have the playlist clips overlaid over existing clips!


Be sure to have a clear track at the very bottom of the current sequence, otherwise the playlist clips overwrite existing clips.