How to upgrade to using the tk-nuke engine for Hiero, Nuke, and Nuke Studio

Note: This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the Shotgun Integrations Admin Guide.

With the release of Nuke 9.0, The Foundry has moved Hiero into being a launch mode of Nuke, plus added Nuke Studio as an all-new application. Shotgun Toolkit now supports all three via a single engine that incorporates the functionality of both the older versions of tk-nuke and tk-hiero, plus adds a number of additional features to help support some of the new, unique workflow features of Nuke Studio.

At the end of this article is a FAQs section. If you have any additional questions not answered here, please contact support.


Get the latest version of Core:

The first step will be to make sure your project is using a new enough version of tk-core. The minimum version required for Hiero is v0.16.31, and for full Nuke Studio support v0.17.0 or later is required. An explanation of how to do that can be found here.



This can be done by using the `tank updates ALL tk-nuke` command for your project, as described here. This will handle updating the tk-nuke version and will also ensure that all new config keys are added where needed.


Nuke Studio:

With the release of tk-nuke v0.5.4 we have thorough integration with Nuke Studio. At its core, Nuke Studio is a melding of Hiero and Nuke into a single application, such that the editing workflow defined in Hiero is combined with the ability to incorporate Nuke node graphs seamlessly into an edit. This capability brings with it the need to understand when a Nuke script is being edited that has been referenced from some shot and task that Toolkit is aware of. The tk-nuke engine, in conjunction with tk-core v0.17.0 or newer, keeps track of what Shotgun Toolkit context is being worked on, and will switch the engine and all running apps to that context on the fly.

Set Toolkit up to launch Nuke Studio:

Nuke Studio is launched as a mode of Nuke controlled by a commandline argument on Windows and Linux, and as a separate .app file within the Nuke application structure on OS X.

Set the paths in paths.yml:


Add the launcher definition to app_launchers.yml:


Add the launcher to the tk-desktop and tk-shell configurations in project.yml:


Configure the tk-nukestudio engine instance in the necessary environments:

The two primary environments that will need to be configured, at a minimum, will be project.yml and shot_step.yml. Others can be configured as necessary for your pipeline. The best approach is to check the tk-config-default repository in Github to see how we have set all of this up on our end. It should act as a good starting point and will get everything up and running smoothly.

Ensure the engine and apps being used in Nuke Studio are up to date:

The performance of the context switching behavior in Nuke Studio is influenced heavily by updates made to almost every app we make available. Below is a list of the apps and their versions as of the initial release of Nuke Studio support. Any version of these apps at that version or newer will be appropriate.

  • tk-nuke (v0.5.4+)
  • tk-multi-launchapp (v0.7.2+)
  • tk-multi-publish (v0.8.7+)
  • tk-multi-workfiles (v0.7.0+)
  • tk-multi-snapshot (v0.6.1+)
  • tk-multi-about (v0.2.0+)
  • tk-hiero-openinshotgun (v0.3.0+)
  • tk-hiero-export (v0.3.1+)
  • tk-nuke-writenode (v1.1.1+)
  • tk-multi-breakdown (v1.4.2+)
  • tk-multi-loader2 (v1.10.4+)
  • tk-multi-reviewsubmission (v0.3.0+)
  • tk-multi-screeningroom (v0.3.0+)
  • tk-multi-setframerange (v0.3.0+)
  • tk-nuke-quickdailies (v0.3.0+)



With the release of tk-nuke v0.4.1 we have moved to allowing the use of a single engine for both Nuke and Hiero. If you are using Hiero 9.0 or later, it will be time to upgrade, making use of the new tk-nuke engine as well as moving to new versions of various apps.

Set Toolkit up to launch Hiero 9.0:

One of the things that The Foundry has done with the 9.0 release of Nuke and Hiero is that Hiero has become a mode of Nuke instead of its own application. This means that we need to change the path that Toolkit uses to launch Hiero, and also add a commandline argument to tell Nuke to launch in "Hiero mode."

Set the paths in paths.yml:


Add the "--heiro" argument and update the icon path in app_launchers.yml:


Make Hiero use the tk-nuke engine:

This is going to involve changing the engine that's being used, updating the version, and adding new config keys. Shown below is the final result with the lines changed or added highlighted. This example is from the project.yml file, which will be the most common place to find a Hiero configuration as it's typically used in a project-level context.


Update Apps for Hiero:

The next step is to run `tank updates ALL tk-hiero` for your project to ensure that the latest versions of apps are being used in Hiero. An update of the following apps is required:

  • tk-hiero-export (v0.2.2+)
  • tk-hiero-openinshotgun (v0.2.0+)
  • tk-multi-workfiles (v0.6.17+)
  • tk-multi-publish (v0.7.4+)
  • tk-multi-snapshot (v0.5.1+)


If you still have trouble:

A good bit of reference to use would be to look at the tk-config-default Github repository. The contents of that config have been updated to include all of the changes mentioned in this article. The specific information you'll be looking for can be found in project.ymlpaths.yml, and app_launchers.yml.



  •  Why does Hiero now use the tk-nuke engine?
    • With the release of Nuke 9.0, The Foundry combined Nuke and Hiero into the same application and added Nuke Studio. Because of this and because of the need to provide both Hiero- and Nuke-like integration for Nuke Studio, we merged the functionality of the tk-hiero engine into tk-nuke, which will be responsible for providing Toolkit integration for Nuke, Hiero, and Nuke Studio.
  • What happens if I setup a new project using the "default" config?
    • The default, multiroot, and flame configs provided during project setups are all now configured for Nuke and Hiero 9.0v7.
  • What if I still use an older version of Nuke?
    • You'll be able to continue as before. Upgrading to the new tk-nuke engine should not have any negative impact on your workflow.
  • What if I still use an older version of Hiero?
    • If an older version of Hiero is being used, the tk-hiero engine is still available for use as before and should not have any negative impact on your workflow.


  • 0
    David van Heeswijk

    Hi Jef,


    Just tested this with Hiero 9.0v8 and getting these errors when I export a shot to Shutgun.

    <!--StartFragment-->ERROR 12:14:37.420:Hiero(13531): NukeShotExporter.taskStep

    Traceback (most recent call last):

    File "/usr/local/Nuke9.0v8/pythonextensions/site-packages/hiero/exporters/", line 672, in taskStep

    return self._taskStep()

    File "/usr/local/Nuke9.0v8/pythonextensions/site-packages/hiero/exporters/", line 969, in _taskStep

    assert(isinstance(writeNodes[-1], nuke.WriteNode))



    Any clue what this is?




  • 0
    Scott Ballard

    Favourite VS. Favorite! UK vs US... LOL

  • 0
    Scott Ballard

    I believe the correct application path on OSx for Hiero (Nuke Studio) is: /Applications/Nuke9.0v8/

    Also no need for the "--hiero" args under OSx.

  • 0
    Andrew Cuthbert


    After we do a "process as shotgun shots" export, and the track items have the nuke tag with the script data in the tag, I'm not getting the "render comp" option, or the ability to "dive into the comp". Is this behaviour set up? And how does it work if you have a combination of "proper" comp workflow and "edit" comps... Wondered if anyone could give me a hand with this.



  • 0

    David did you ever find a solution to that error?I just come across the exact same issue.



Please sign in to leave a comment.