ShotGrid Engine for Houdini

ShotGrid Pipeline Toolkit integration in Houdini
Latest Version: v1.8.1 (prod)
For our version numbers, we follow the Semantic Versioning standard.
System Name: tk-houdini

Please Note: This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the Shotgun Integrations User Guide for more details.
Overview Summary
      Information for App Developers
            Supported platforms
            Menu loading
            Shotgun shelf
            Apps with OTLs
            Startup Debugging via Terminal on OSX
Installation, Updates and Development
Configuration Options
Release Notes History

The Shotgun engine for Houdini establishes a bridge between the Shotgun Pipeline Toolkit apps and Houdini. It contains a Qt/PySide distribution for Windows, which is compatible with the python version bundled with Houdini, making it possible to write apps using Python and PySide that run right inside the engine.

Supported Application Versions

This item has been tested and is known to be working on the following application versions: 14.0 - 18.5. Please note that it is perfectly possible, even likely, that it will work with more recent releases, however it has not yet been formally tested with these versions.

Overview Video

The following video gives a quick overview of features and functionality.


The Shotgun Engine for Houdini contains a standard platform for integrating Shotgun Apps into Houdini.

Shotgun Engine for Houdini

Information for App Developers

Supported platforms

The Shotgun Engine for Houdini is currently supported on Windows, Linux, and OSX


For older versions of Houdini (13 and older) an external build of PySide is required. On Windows, we have bundled a compatible PySide build that will work with the python that Houdini runs. On Linux, Houdini uses the system python (per http://www.sidefx.com/docs/houdini12.0/hom/) which needs to have PySide or PyQt support.

Menu loading

Shotgun menu

A dynamic menu system was introduced by Side Effects as of Houdini 15, so the engine now supports rebuilding of the Shotgun menu on context switches.

In Houdini 14 and older, the Shotgun menu in Houdini is generated before Houdini starts and is static throughout the session. Due to this, the toolkit commands registered in the menu will not update on context changes.

Shotgun shelf

Shotgun shelf

Release v0.2.4 introduced a dynamic Shotgun shelf to the engine. The shelf displays any registered app commands as tool buttons. The buttons will be displayed in roughly the same order as the menu commands.

Use the enable_sg_shelf setting to turn on the shelf within an environment. If using a version of Houdini (14 or older) that does not support dynamic menus, you may also want to turn off the Shotgun menu when using the shelf. This can be done by setting the enable_sg_menu setting to false.

To enable context switching via the shelf, you'll also need to add entity types to the sg_entity_types setting of the tk-multi-workfiles app in your engine configuration.

Here's a look at the settings related to the Shotgun shelf:

    # ... other app definitions
       # ... other app settings
       sg_entity_types: [Shot, Asset] # allow context switching to Shots or Assets
       # ... other app settings
  enable_sg_shelf: true
  enable_sg_menu: false
  # ... other engine settings

Once you've enabled the Shotgun shelf, you need to manually add it to a shelf set inside houdini.

Add the Shotgun shelf

Once added to a shelf set the Shotgun shelf will remain there between houdini sessions and will update dynamically as your shotgun context changes.


As of v0.2.8 the engine adds support for embedded toolkit panels.

The panel support currently requires Houdini version 15.0.272 or later for proper embedded panels. Registered panels will show up as panes in the pane menu for supported versions of Houdini.

Older versions of Houdini will display the registered panels as dialogs. SESI may backport some bug fixes to newer builds of Houdini 14. If and when that happens, we will make embedded panels work for those versions as well.

Apps with OTLs

The Shotgun Engine for Houdini makes it easy to load application supplied OTLs. If you are writing an app which uses OTLs, you can just drop them into a folder called otls and the engine will automatically load them into your session:

Houdini OTLs

You can then easily access your nodes via the usual Houdini methods.

Warning!! Please note that while the use of OTLs may be convenient, it is typically NOT the right solution if you want to create nodes that persist in a scene. The reason for this is because as soon as you have put an OTL in the scene, you have introduced a dependency between that scene and the OTL code. Not only will you need to load the Shotgun Toolkit every time you load the scene, but you also need to carefully manage your code so that any updates to the code does not break old OTLs being used in scenes.

Startup Debugging via Terminal on OSX

Turning on debug_logging for the tk-houdini engine on OS X will not send all debug messages to the Terminal. This is because, by default, the tk-multi-launchapp app uses the open command to launch executables. This does not spawn a new subprocess from the Terminal, but rather uses OS X's Launch Services to create a new process elsewhere. As a result, the log statements are not shown. Even having a python shell saved in the user's default desktop in houdini does not seem to show debugging statements during startup. After startup, and embedded python shell will show debug logging statements, but there is a gap in available output during startup. If you need access to debug logging statements during engine startup, you can make 2 changes.

First, change your houdini_mac path (temporarily) in your test configuration to point to the executable inside the Houdini app bundle. For example:

#houdini_mac: /Applications/Houdini 15.0.272/Houdini Apprentice.app
houdini_mac: /Applications/Houdini\ 15.0.272/Houdini\ Apprentice.app/Contents/MacOS/happrentice

Next, you can make a copy of the tk-multi-launchapp app's app_launch hook in your test configuration's config/hooks directory and point to it in your config/env/includes/app_launchers.yml file:

  defer_keyword: ''
  engine: tk-houdini
  extra: {}
  hook_app_launch: app_launch    # <----- use a custom app_launch hook
  hook_before_app_launch: default
  icon: '{target_engine}/icon_256.png'
  linux_args: ''
  linux_path: '@houdini_linux'
  location: {name: tk-multi-launchapp, type: app_store, version: v0.6.6}
  mac_args: ''
  mac_path: '@houdini_mac'
  menu_name: Launch Houdini
  versions: []
  windows_args: ''
  windows_path: '@houdini_windows'

Then all you have to do is modify the launch logic to launch the executable directly. As an example, you could keep the old behavior for directories (application bundles) and otherwise execute the command directly. Here's an example:

        elif system == "darwin":
            # on the mac, the executable paths are normally pointing
            # to the application bundle and not to the binary file
            # embedded in the bundle, meaning that we should use the
            # built-in mac open command to execute it
            if os.path.isdir(app_path):
                cmd = "open -n \"%s\"" % (app_path)
                if app_args:
                    cmd += " --args \"%s\"" % app_args.replace("\"", "\\\"")

            # not a directory, execute directly
                cmd = "%s %s" % (app_path, app_args.replace("\"", "\\\""))

The next time you run launch_houdini via tank in the Terminal, you should get all the debug output. Once you're done testing, don't forget to revert your path and undo your app launch changes. Happy debugging!

Installation and Updates

Adding this Engine to the Shotgun Pipeline Toolkit

If you want to add this engine to Project XYZ, and an environment named asset, execute the following command:

> tank Project XYZ install_engine asset tk-houdini

Updating to the latest version

If you already have this item installed in a project and you want to get the latest version, you can run the update command. You can either navigate to the tank command that comes with that specific project, and run it there:

> cd /my_tank_configs/project_xyz
> ./tank updates

Alternatively, you can run your studio tank command and specify the project name to tell it which project to run the update check for:

> tank Project XYZ updates

Collaboration and Evolution

If you have access to the Shotgun Pipeline Toolkit, you also have access to the source code for all apps, engines and frameworks in Github where we store and manage them. Feel free to evolve these items; use them as a base for further independent development, make changes (and submit pull requests back to us!) or simply tinker with them to see how they have been built and how the toolkit works. You can access this code repository at https://github.com/shotgunsoftware/tk-houdini.

Special Requirements

  • You need Shotgun Pipeline Toolkit Core API version v0.19.1 or higher to use this.


Below is a summary of all the configuration settings used. These settings need to be defined in the environment file where you want to enable this App or Engine.


Type: bool

Default Value: True

Description: Controls whether toolkit should attempt to automatically adjust its context every time the currently loaded file changes. Defaults to True.


Type: bool

Default Value: True

Description: Controls whether a menu will be built with commands registered by the installed apps. It is not currently possible to rebuild the menu on a ShotGrid context switch, so this option allows for the menu to be disabled in favor of the ShotGrid shelf which can be rebuilt dynamically.


Type: bool

Default Value: True

Description: Controls whether a shelf will be built with commands registered by the installed apps. The shelf will be rebuilt dynamically as the ShotGrid context changes.


Type: bool

Description: Controls whether debug messages should be emitted to the logger


Type: list

Description: Controls the favourites section on the main menu. This is a list and each menu item is a dictionary with keys app_instance and name. The app_instance parameter connects this entry to a particular app instance defined in the environment configuration file. The name is a menu name to make a favourite.


Type: list

Description: Comma-separated list of tk-houdini plugins to load when launching Houdini. Use of this feature disables the classic mechanism for bootstrapping Toolkit when Houdini is launched.


Type: list

Description: Controls what apps will run on startup. This is a list where each element is a dictionary with two keys: 'app_instance' and 'name'. The app_instance value connects this entry to a particular app instance defined in the environment configuration file. The name is the menu name of the command to run when the Houdini engine starts up. If name is '' then all commands from the given app instance are started.

Release Notes

Welcome to the release notes for this Engine. Below you will find an overview of all the changes we did for each release. We try to be as detailed as possible and include all bugs we have fixed, features we have added and things that may have changed. If you have questions about a particular release, don't hesitate to contact our support team!



Rebranded to ShotGrid



Fixes a bug, introduced in v1.7.0


Fixes an issue on Linux in Houdini versions 17.0 and before, where it would error on start up.



Adds a bug fix and a small feature.


  • Fixes an issue where the engine wouldn't load app otl files in Houdini on startup when there was no GUI present (which could be done by launching hython). A big thanks goes out to Patrick Macdonald for providing this fix!
  • Adds a small feature to allow the Houdini engine to load version specific otl files from an app. An app can now have version folders inside their otl folder that represent the Houdini version, and the engine will load the otls that best match the current Houdini version. For example you could have a otls/v16.x.x folder and a otls/v18.x.x folder and if you were running Houdini 17 it would choose to load any otls from the v16.x.x folder, since it will try to load the otls from the closest matching version folder that is either the current version or lower.



Adds support for Python 3.



There are Qt-related stability issues in Houdini 18 in builds older than 18.0.348. We've now worked around one and warned of others at launch time.


Early builds of Houdini 18 come with some stability problems related to Qt/PySide2. In one of those cases we have been able to work around the issue at the expense of window parenting behavior for Toolkit dialogs. In others, however, we were unable to properly fix or work around the issues. As such, in Houdini 18 releases older than 18.0.348, we now display a warning dialog on launch to inform users of the potential stability issues they may encounter.



Fix for open file on startup behaviour.



Fixes slow startup on 17.0.506



Compatibility fixes for Houdini 17.



Fixes a Qt dialog raising fatal error on Windows in Houdini 16.5.481+



Toolkit panel apps no longer causes built-in Houdini pypanels to be removed from the python pane menus.


Previously, we installed Toolkit panel apps to python pane menus in a destructive manner. This caused a few out-of-the-box Houdini pypanel apps to be removed from menus. This release also fixes a QCheckbox styling problem that resulted in missing check icons in panel apps.



Additional fix for slow Houdini startup when launched from a Task entity on Windows.


This fix is tied to when we load otls from disk for Toolkit apps. What was being done was correct, but when it was being done during startup of Houdini caused a pause in the launch that could take quite some time.



Fix for slow Houdini launching on Windows.


This is tied to our shelf population logic, but it doesn't appear to be anything we're doing wrong. Rather, as best as we can tell, it's WHEN our logic is being called during launch that causes Houdini to pause for some time. The fix is to defer the shelf population by an event loop cycle, which seems to resolve the issue without any ill effects.



Changes how we path to a checkbox image in qss. No visible change in functionality or styling.


Some issues around workfiles2 were reported by a few clients related to the os.chdir call we added as part of the v1.5.1 release of the engine. To address these issues, we've changed approaches to allow us to remove the os.chdir call.



Fixes a styling problem for checkboxes in Houdini 16.x on Linux.



Resolves a bug that caused panel apps to not load when launched from Houdini's native pane tab menu.


A mechanism was in place that renamed new PaneTabs in such a way that the engine could later identify it. This allowed us to activate an existing Shotgun Panel instance if one had been launched, rather than showing a duplicate. This breaks Houdini 16.x, however, so we've had to implement an alternative approach to get the same result.



Minor tweak to styling to help with text readability in some views.



Minor tweaks to scrollbar styling to make them prettier and easier to use.



Minor color fix for QMenu to make the menu item text more visible.



Styling fixes for Houdini 16.x.


Our old approach to styling from H15 and under causes problems with H16.x, where some of our style changes bleed into Houdini's dialogs. As such, we've had to take a different approach to styling for H16+.



Now houses publish2 plugin hooks and supports template-based worklfows



Stops Toolkit dialogs from falling behind Houdini on OS X.



Styling fixes for the Shotgun Panel app in H16 on OS X.


This change goes along with the temporary disabling of panel support for H16 on OS X in v1.2.5. When panel support is re-enabled, this styling change will also be removed.



Disables panel support for H16 on OS X.


This is a temporary measure while possible fixes for panel painting issues are discussed with SESI engineers. Our panel apps function properly on OS X in dialog mode, so that is the route we'll have to go for the time being. Panel support remains unchanged on Windows and Linux operating systems.



Bundles in a missing urllib2.py and fixes QLabel styling in H16.



Fixes to improve compatibility with Houdini 16.


Compatibility with Houdini 16 is improved. Engine-level qss has been added to address styling problems with Qt apps, and fixes for ssl compatibility with Python modules bundled with Houdini are included. There continues to be a Python pane problem on OS X, resulting in the Shotgun Panel app having some visual problems on that operating system.



Minor adjustments to logging output



bumps required core version to v0.18.45



Adds support for launching Houdini using the new Software entity setup in Shotgun. It also includes a houdini plugin that can run standalone or directly from within the engine.



Removes bundled PySide and updates to new logging style



Guard automatic context switching with a check of the engine config setting



Use existing path separator, fallback to os.pathsep



Use existing path separator, fallback to os.pathsep



hot fix for houdini bug when mouse over shotgun menu buttons.



Safer logic for modifying HOUDINI_PATH during bootstrap



Safer logic for modifying HOUDINI_PATH during bootstrap



Adds support for context switching when using the Recent Files menu in Houdini



Adds support for context switching when using the Recent Files menu in Houdini



Adds support for context switching when using the Recent Files menu in Houdini



Fix for embedded panel regression



Adds a call to log a user metric for the DCC version



Houdini engine 1.0 release. Supports H14, H15, OSX, reloadable menus, tk panels and more.



QA polish and fixes for houdini engine update



Added dynamic Shotgun menu for Houdini 15+. Menu now updates with context switching.



Make toolkit apps look nice and consistent inside Houdini



Panel support in houdini



Limits engine support on OS X to Houdini 14+



Updates tk houdini engine for Houdini 14



Fix for UNC paths for shelf icons



fix to allow Shotgun shelf to work in houdini 13



Updated Houdini to support dynamic shelf for registered commands


Fixed issue where an exception was raised whenever a dialog was shown using engine.show_dialog or engine.show_modal


Fixed issue with UNC paths on Windows when creating menus


Updated engine to use new dark theme. Misc tweaks and fixes.

Details: - The engine now uses the new dark theme introduced in 0.14.56. Toolkit UIs running in Houdini now look more similar to Maya's UI look and feel. - Error logging no longer pops up error messages in dialogs, instead it just logs a message. This is consistent with they way other engines work. - Since houdini runs its python console in a separate thread, running toolkit command from the console which results in UI generation would previously crash the system. Added protection for this so that if a UI is launched outside of the main UI thread, an error message is raised.


Updated PySide version handling to support very old versions!


Support for Houdini 13 and Python 2.7

Details: Support for Houdini 13 and Python 2.7


Fix for PyQt on linux.

Details: Fix for PyQt on linux.


Fix to let the engine run from houdini batch and hython.

Details: Fix to let the engine run from houdini batch and hython.


Updated PyQt compatibility


Updated to support PyQt

Details: Updated to support either PyQt or PySide. PySide will be preferred if it is available.


PySide bundled for Windows. Houdini version check. Unicode support. Fix for debug output.

Details: PySide for Windows is now bundled. As linux uses the system python, docs updated to reflect that dependency. Version check added for Houdini version 12+ Unicode support in PySide Fix for being able to turn off debug output.


sgtk windows now first appear above houdini.

Details: Added os specific support to make sure that sgtk dialogs do not appear behind Houdini


Experimental Release of the new engine version to the app store.


Updated manifest to be 0.12.5 compatible


Minor changes to work nicely with core v0.12.5


Initial release to the App Store.