Shotgun Integration

ShotGrid Engine

Toolkit Integration in ShotGrid
Latest Version: v0.10.0 (prod)
For our version numbers, we follow the Semantic Versioning standard.
System Name: tk-shotgun

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.

The Shotgun Engine makes it possible to integrate Shotgun Pipeline Toolkit Apps right into Shotgun. These will appear inside of Shotgun on the Action menu and can be attached to most project-centric entities. You can, for example, launch an application straight from a task, or launch apps that handle deliveries of Review Versions, Summaries or reports for Shots or Notes.


The Shotgun engine manages apps that can be launched from within Shotgun. Sometimes we refer to these Toolkit Apps as Actions. They typically appear as items on menus inside of Shotgun.

Using Shotgun Pipeline Toolkit Actions

Actions are visible on the Shotgun Home page:

Tank Actions

They can also be found on the standard Shotgun context menu, which can be shown by right clicking on an object or a selection:

Tank Actions

When you click on an action, processing will immediately start. Once the app has completed, a message is typically displayed with some status information, or an error message if things didn't work.

Developing Apps for Shotgun

Developing apps that run inside of Shotgun is easy! If you are not familiar with how app development works in general, head over to the Platform documentation and read the introductory material over there. In this section we will just cover the Shotgun specific aspects of the app development process!

As of Core v0.13, you can use all the multi apps with the Shotgun Engine. Technically speaking there is little difference between the Shotgun engine and other engines. There are, however, some subtle differences:

  • You will need to manually install PySide or PyQt into your standard python environment if you want to execute QT based apps in the Shotgun Engine.

  • It is possible in the Shotgun engine to make an action visible to a user depending on which permissions group they belong to. This is useful if you want example want to add a command to the Shotgun Action menu and you only want admins to see it.

A hello-world style Shotgun App, only visible to admins, would look something like this:

from tank.platform import Application

class LaunchPublish(Application):

    def init_app(self):
        Register menu items with Shotgun
        params = {
            "title": "Hello, World!",
            "deny_permissions": ["Artist"],

        self.engine.register_command("hello_world_cmd", self.do_stuff, params)

    def do_stuff(self, entity_type, entity_ids):
        # this message will be displayed to the user
        self.engine.log_info("Hello, World!")

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-shotgun

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

Special Requirements

  • You need Shotgun Pipeline Toolkit Core API version v0.19.5 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

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

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



Adds Python 3 compatibility



Updated to require core 18.24 for QT5 compatibility.



Improvements to PySide2 Support.



Added support for Pyside2.



Updated for use with new core metrics



Allows on-the-fly context changes.



Adds back in Qt library path clearing, but only for KDE Linux.



Removes the clearing of Qt library paths introduced in v0.5.3.


This has been removed in favor of a safer and more-targeted implementation of the same in tk-multi-launchapp.



Fixes crashes on multiple Linux distributions when QT_PLUGINS_PATH is set.



Updated Shotgun icon


Improved logic for indication of a UI present


This changes the meaning of the has_ui property so that it is consistent with other engines. Previously has_ui would return True as soon as a valid pyside/pyqt4 was detected. This is inconsistent with other engines, where has_ui indicates that an active UI is present and running. This pull request adjusts the shotgun engine so that has_ui only returns true when a QApplication is actually active in the system.


Updated visual style to better match Maya.

Details: This change affects the visual appearance of all apps running in the engine, making their visual appearance much more consistent with the look and feel that you would get inside Maya. Please note that after this upgrade, app UIs will look slightly different.


Updated PySide version handling to support very old versions!


Updated engine icon.


Added support for multi-select style UI apps.


Updated PyQt compatibility


Now uses the built in QT stylesheet introduced in Core v0.14.28.


Updated QT Style Sheet to include a border around text input elements.


Better Support for unicode.


Fixed a bug where debug logging was supressed from the output despite the debug flag being set.


Renames and support for the new name Sgtk.


Added PyQt Support.

Details: * Engine now supports PyQt4 for UIs. This is detected at runtime, and if
tank can load PyQt4 from the python system path, it will attempt to use it. This is a fallback in case PySide is not found. * Better error messages when PySide/PyQt4 is not installed - the engine now presents some more polished feedback in the case a UI based app is launched but neither PySide nor PyQt exists to handle the UI creation.


Fixed a bug which could cause apps raising Exceptions to be stuck in a loop.


Minor adjustments to PyQt4


Better QT App Support.


Added icon.


Updated manifest to require core v0.12.5


Fixed formatting bugs related to html characters and certain exceptions being raised.


Bug 19097: < and > Characters are now html escaped and no longer swallowed in the output.


First Release with the new Tank API.


Initial release to the App Store.