Shotgun Desktop

ShotGrid Desktop

The engine that runs inside the ShotGrid Desktop Application
Latest Version: v2.6.0 (prod)
For our version numbers, we follow the Semantic Versioning standard.
System Name: tk-desktop

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 Desktop Engine is the engine which runs inside of the Shotgun Desktop Application. It handles UI functions and establishes a bridge between Toolkit apps and the Shotgun Desktop Application.

Overview Video

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


The tk-desktop engine is an application to let you easily run your Toolkit apps. It is a system tray based window that makes it easy to get started with Toolkit, setup Projects for Toolkit, and access your Projects' pipeline.

If you have already set up your first project and you are looking for help configuring it to meet your needs, see our 'next steps' documentation:

Site configuration and Project configuration

When you launch the desktop application, it will startup the tk-desktop engine for your site configuration. This configuration is usually automatically managed, although it is possible to disable that behavior and take control over what is in that environment.

One of the fundamental principles of Toolkit is that projects can be completely isolated from each other. This is usually done to make sure that changes made to one project cannot adversely effect another project (possibly nearing delivery). In order to offer this project isolation, the desktop engine makes sure that whenever you are looking at the commands for a particular project, you will run them in a separate python interpreter that has been initialized just for that project.

When you click on a project, a python interpreter is launched in the background. This python interpreter is the one the project has been configured to use and on startup will initialize the tk-desktop for that project. That instance of the engine will communicate back to the GUI what commands it can launch.

When you click on a command, that background python process is responsible for launching the command. This makes it possible (for example) to have one project running python 2.6 while testing python 2.7 on another project.

Registering custom panels

Toolkit apps which have panel based UI will be automatically docked in tabs inside of Desktop when they execute.

If you have a panel based app such as the Shotgun Panel, and want it to appear as a tab in Shotgun desktop, just configure it to run at startup. When Desktop starts up in its site context mode (where it displays all projects), it will launch all items registered to auto start. If any of these items are panels, these will get docked. Items will be processed in the order they are defined in the configuration and this will dictate the tab order.

For example, if you wanted the Shotgun Panel to show as a tab in Shotgun Desktop, add the following configuration for your site level environment:

      actions_hook: ...
      action_mappings: ...
      location: ...
  location: ...
  - {app_instance: '', name: Apps}
  - {app_instance: tk-multi-shotgunpanel, name: ''}

Please note that the special Apps entry controls where (in the tab order) the default Apps tab should appear.

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

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.18 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: str

Default Value: CustomNonProjectEntity23

Description: ShotGrid CustomNonProjectEntity designated as the Software entity until it becomes native.


Type: str

Default Value:

Description: Link to a ShotGrid Support article detailing how to configure Software entities for a site.


Type: bool

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


Type: str

Default Value: Studio

Description: Controls the name of the default command grouping for any commands that do not match any of the values in the groups setting.


Type: list

Default Value: [{'app_instance': '', 'name': 'Apps'}]

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 desktop starts up. If 'name' is '', then all commands from the given app instance are started. To add the 'Apps' tab (which contains the app launcher), add the following startup command to the list: {app_instance: '', name: 'Apps'}


Type: list

Description: A list of dictionaries that define what commands get put in which groups. Each dictionary entry needs to have the following keys: name - the name of the group, matches - a list of strings for what commands to add to the group. As commands are added to the engine, each match from the group's matches list will be treated as a case insensitive glob style match against the command's display name. If there is a match then the command will be added to the group. For example 'Maya' will match against any command that contains the string 'maya' in the display name, regardless of case. It is possible for a command to show up in multiple groups if it has matches against multiple groups.


Type: bool

Default Value: True

Description: Controls whether to show the recently clicked on commands


Type: list

Default Value: [{'button_label': '$app', 'match': 'Launch $app', 'menu_label': 'None'}]

Description: A list of dictionaries that define how to collapse multile commands into a single button in the GUI. Each dictionary needs to have the following keys: match - a string that will match against the display name of a registered command, button_label - what the text label of the resulting button should be, menu_label - what the text label of the item in the button's menu should be. As commands are added to the engine, their display name will be compared to each match in turn. The match string can contain '$' style variables, which will be matched against any single word in the dislay name of the command. Those '$' variables are available for use in the button_label and the menu_label. For example a match of 'Launch $APP $VERSION' will match any display name made up of 'Launch' followed by two words. If the display name is 'Launch Maya 2014' then this would match, and the value of '$APP' would be 'Maya' and the value of '$VERSION' would be '2014'. If menu_label is the special string 'None' then the button name will be translated per the value of button_label, but no menu entry will be added for the commands. If multiple commands collapse down to a button in this way, only the first one will be registered. If a display name does not match any collapse rule, then it will show up as a button without any menu. The first matching rule will determine the button and menu labels.


Type: hook

Default Value: launch_python

Description: This hook is responsible for launching the python interpreter for a specific project. The first argument to the hook is 'project_python', the path to the python interpreter to be launched. The next argument to the hook is 'pickle_data_path' which is a full path to a python pickle that contains the info needed to initialize the project's tk-desktop engine and talk back to the desktop GUI. The third argument is the path to a utilities python module. This module should be loaded in the new interpreter and used to start up the engine.

Release Notes

Welcome to the release notes for this App. 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



Updated the about box.



Fixes an error that occurred when opening SG Desktop and restoring the previous window position.



Switches from using the support email alias to pointing to the support site



Better user experience for first time users of the Shotgun Desktop.


  • Shotgun Desktop's dialog will now be displayed the first time it is launched instead of being minimized to the system tray.
  • When a first-time user closes the dialog, a pop-up will be shown letting them know the app is now in the system tray. Due to a limitation on macOS, builds older than v1.6.1 will not show this message.



Adds a license box.



Fix for a rare startup bug, that would prevent launching Shotgun Desktop.



Fixes an issue when running the browser integration under Python 3.


Note that as of this release, a Python 3 version of Shotgun Desktop has not been released... yet. Be patient. :)



Fixes an issue on MacOS where keyboard input couldn't be entered on any Toolkit apps launched from a project in SG Desktop.



Make sure the engine shuts down properly by calling destroy() and not destroy_engine()



Multiple fixes for the Shotgun Desktop running with Python 3.



Fixes icon highlighting when opening a project and better handling of projects launched with Python 3.


  • We've improved error reporting when launching a project with Python 3 when some components in that project are not Python 3 compliant.
  • Fixed an issue where proxy settings could prevent a project from being launched.
  • We've fixed an issue where icons get highlighted and stay highlighted when the mouse cursor is over the Shotgun Desktop after opening a project.



Projects using a Python 3 interpreter can now be launched from Shotgun Desktop.


Once a project has been configured to use Python 3 by editing the config/core/interpreter_<os>.cfg file inside a centralized configuration or the core/interpreter_<os>.cfg inside a distributed or descriptor-based configuration, Shotgun Desktop will launch that project with Python 3.

Thank you to @aparna-d2 for providing the PySide2 support code.



Fixes a regression in the last release, where python processes would be left orphaned instead of being closed when leaving the project in Shotgun Desktop.



Shotgun Desktop should now log a full error traceback if an error occurs when loading a project configuration, or when running an app.



Fixes a bug where Project Filesystem Folder would not be displayed in the Desktop menu.


Note that this fix is applicable only to projects configured through the Advanced Project Setup. Cloud-based and descriptor-based configurations cannot display this menu item at the moment due to a technical limitation.



Bumps required core version to v0.18.143



Better error handling when tank_name is not set on a project.



Shotgun Desktop will now provide a clearer error message when a pipeline configuration has not been properly configured.



Shotgun Desktop will not freeze when downloading big configurations from Shotgun.



Resolves an issue where errors raised during bootstrap were not reported to the user on Windows.



Fixed project menu duplicated items on invoking 'Reload and Restart' also updated metrics logged.



Fixes project menu duplicating menu items on invoking 'Reload and Restart'



Adds debug logging toggle to Advanced menu



Update engine to use newer metrics API



Updated to make use of the new metrics API provided by tk-core.



Hides Regenerate Certificates option when using



Ensures widget instance is properly returned from show_panel



Fixes a crash that occurred immediately after selecting a project using Python 2.6.



Fixes an issue when a project uses a Toolkit core more recent than the Shotgun Desktop.



Fixes a bug causing panel dialogs not to open when in project mode.



Custom panels now pick up standard stylesheets.



Adds support for tabs and apps running at startup.



hot fix for first launch notification



This release fixes some UI issues in addition to reporting usage statistics to Shotgun about which version of the Shotgun Desktop is being used.


The various UI enhancements fixes are: - Product name is no longer displayed twice on shortcuts. - Adds a Help menu to the user menu. - Fixed some links pointing to outdated documentation. - Toolkit apps launched from the Shotgun Desktop will now log back to the Shotgun Desktop console.



Is it now possible to regenerate the browser integration certificates from the user menu.



Fixes an issue with unicode strings and environment variables on Windows.



Adds support for Shotgun Integrations.



Fixes an issue where sometimes an empty dialog would appear when launching an app on Windows.



Fixes an authentication related issue and a window positioning bug on Windows 10.


  • On Windows 10, the Shotgun Desktop dialog will not be cropped if the tray area is too small.
  • Fixes an authentication issue that can arise when using 0.18-based projects with Shotgun Desktop. In those circumstances, the Shotgun Desktop would not display the available Toolkit applications after selecting a project.



Show or hide project menu item 'Project Filesystem Folder'.


Show or hide project menu item 'Project Filesystem Folder' based on the availability of the project locations.



Fixes multiple UI issues.


  • The project menu at the top right no longer grows as you switch pipeline configurations.
  • The "Refresh Projects" menu item in the user menu at the bottom right is no longer present when inside a project.
  • The "Setup Project" message is no longer rendered over the launcher icons after configuring a project.



Fixes a bug where logging a non-string value with log_exception would raise an exception.



Fixes a bug where logging a non-string value with log_exception would raise an exception.



Updates the framework dependencies to the latest major version.



Fixes for hanging Python processes and the initial launch of a dialog being hidden.


This release fixes an issue where the Shotgun Desktop will not properly close Python subprocesses when switching project or the Shotgun Desktop is closed. It also fixes an issue on Windows where the first launch of a GUI based Toolkit application will not show any UI.

While the Desktop application and the pipeline configuration can be updated separately, both need to be updated to fix the Python process leaks.



Fix for exception that can occur when turning show_recents off. Note: v2.0.14 and v2.0.15 were skipped due to issues found in QA.



Minor improvements to management of recent apps settings



minor improvements to management of recent apps settings management



No longer use the event log for tracking recent activity


Improves performance by storing recents using the settings module instead of requiring calls to Shotgun.



Clicking the search icon automatically focuses the text widget.



Friendlier error behaviour on empty OS path


Friendlier error messages and allow to change the pipeline config even if loading the current config failed.



Change the tray icon to fit in OSX Dark mode.


When restarting the Desktop, the login screen will always be displayed.


In the newest version of the Shotgun Desktop, not being logged in on startup sends the user in tray-mode. The user then needs to click on the tray icon and pick "Sign in to Shotgun Desktop" in order to login. When signing out of the Desktop however, the Desktop will be restarted and jump straight into the login screen.


Fixed a bug on Windows where restarting the Shotgun Desktop kept port 9000 alive even tough the Desktop had been closed.


Once you have restarted the Shotgun Desktop and let it auto-update itself, you will probably encounter the port 9000 issue again. You will need to quit all applications that were launched from the Shotgun Desktop or from a web browser. You will also need to close the Shotgun Desktop itself. Then launching the Shotgun Desktop again should work without any issues.

If you still encounter the port 9000 issue, something else might be holding on to it. Please log out of your Windows user account and log back in. This should definitely release the port 9000 once and for all and then the Shotgun Desktop will able to launch and close port 9000 correctly in the future.


Adds support for two factor authentication using the 1.0.x Shotgun Desktop.


Fixes the Project Filesystem Folder launcher.


Fixes a crash when adding the tk-desktop engine to the project context.


Users only see the projects they have permissions for.


Tweaked when credentials are refreshed.


When the project configuration is login based, the desktop engine will refresh the credentials before launching any app, possibly prompting the user for this password., even if the site project is script based.


Added support for login based authentication from v0.16.0.


Added support for login based authentication from v0.16.0.


Release Candidate 9.


Better error handling around missing Python interpreter. Misc changes.


  • Better checks and prompting when python is not found a project.
  • Fixed issue with font sizes being inconsistent across operating systems.
  • Updated copyright notice.


Fixed a bug with Shotgun Desktop 1.02.


Fixed a bug with Shotgun Desktop 1.02.


Filtering out Shotgun 6.0 Template Projects from the project selection screen.


Filtering out Shotgun 6.0 Template Projects from the project selection screen.


Display better error message when project is already set up


About Box now displays the version of core.


About Box now displays the version of core.


Instrument time spend querying event logs.


Fix for crash if there is an error on logout.


Fix for windows subprocess bug when updating project config on Windows.


"Always on Top" Setting Disrupts "Browse" Windows in Setup Wizard


When browsing for a config in project setup wizard on mac, the file finder appears under every one of our windows. This fixes the issue by removing the always on top setting while the wizard is running.


Update the project python bootstrap to reset PATH


Prevents DLL loading issues with some engines (maxplus) on windows.


Bug fix for when the model storing project data has no associated Shotgun data.


Updated manifest with tweaked display name and description.


Updated documentation


Visual polish and a few small bug fixes.


  • Sort commands within groups alphabetically
  • Visual polish for the setup new os screen
  • Pack command widgets in a little tighter
  • Items in the command menu are sorted latest version to oldest version
  • Default button action is the first action in its menu
  • Limit the number of recent commands
  • Fix for floating editor when scrolling commands
  • Update to use login framework v1.x
  • Switch to subprocess for restart on log out for better Windows behavior


Bug fix and handle projects not set up for current OS.


  • Added screen for when a configuration has not been set up for the current os
  • Fix for projects not showing up on first launch
  • Dark icon for default user thumbnail


Updated to be compatible with the new splash screen. New project icon.


Visual polish. Fix for copying from the console.


Fix for right clicking on a project or command triggering it Fixed Console menu. Made copy work. Search icon highlights on hover Preserve Project thumbnail size and grow to handle long Project Names Clip long project names for the project header Pretty up the Shotgun and User buttons a little Default values to strip "Launching" from default config's launcher setup Updated about screen


Fix for bug that broke project filtering via the search box


Lots of GUI changes.


No longer show the console automatically Remove preferences dialog Project thumbnails squared Fix for auto-hide when a sub-dialog got focus Don't show empty groups About screen No recent projects shelf Various other visual tweaks


Major update of the engine, including setup project UI and no requirement for PySide/PyQt for project pythons.


  • Added setup project UI for when clicking on a project that has not been setup in Toolkit
  • Added instructions for turning on Toolkit when connecting to a site with Toolkit off
  • Remember what groups are expanded
  • Console window for logging
  • Highlight matching characters from the fuzzy search algorithm
  • Use the login framework
  • Added ability to refresh the project model


Fix for disabled Shotgun menu in some launched apps.


Override python icon. Better logout behavior. PyQt support for project python.


Use v2 of the shotgunutils framework.


Added a hook to launch python and updated the gui code to be more model/view based.

Details: New hook that lets studios take over the launching of the project specific python if they need to. Updated the GUI code to be more model/view based so commands are more consistent.


Bug fix to explicitly add .pyd file on windows for osutils extension.


Added ability to choose Pipeline Configurations other than Primary.


Better systray click handling. Raise hotkey and start on login options.


Added project loading spinners and a splash screen.


Update the version of the shotgunutils framework.


Support for docking to any side of the screen and stylesheet for sub-process.


A bunch of little fixes. Better (but not yet great) windows support.


Initial app store release.


Initial test release



  • 0
    John Coldrick

    In terms of best practices going forward, does it make sense to say that in an ideal world, the path to python in the site-wide Shotgun config will eventually be set to the bundled python that comes with the shotgun desktop?  I realize technically that's not required, and larger shops might well have all sorts of reasons to point to their own, but would that be a good idea?  Right now we have a config that points at C:\Python26, I was thinking about upgrading everyone to 27, but there's something to be said for pointing it to C:\Program Files\Shotgun\Python, right?

  • 0
    Mitchell Lotierzo

    I may be doing something wrong, but it seems like the "groups" configuration setting isn't working. I have it set to:


    - {name: Softimage Tools, matches: ['Softimage']}

    - {name: Nuke Tools, matches: ['Nuke']}


    The only group I see in the UI is "Studio" still.

  • 0
    Rob Blau

    Hi John,

    We intend the built in python to be a good option for your configs.  We bundle in some modules that are used in the toolkit code (PySide being the big one, but also something like the win32 module which the login framework can use if available) which makes it easy to setup.  If you are going to be installing the desktop for everybody, then either choice should work for you, but pointing to ours would mean that you have slightly more up to date installs (python 2.7, Qt 4.8, PySide 1.2.1).

    We aren't going to mandate that infrastructure for your projects, but we do want to have it readily available as a good option if you want to use it.

  • 0
    Rob Blau

    Hi Mitchell,

    The syntax for the groups setting needs a glob style string for the matches.  If you do something like this, do you start seeing what you'd expect?


    - {name: Softimage Tools, matches: ['* Softimage *']}

    - {name: Nuke Tools, matches: ['* Nuke *']}

  • 0
    Mitchell Lotierzo

    That works. Thanks for that little bit of guidance :)

    I've also noticed something in the console that may be of concern. It looks like it is pulling PySide from the Fabric Engine directory?

    "2014-08-14 12:01:35,829 [ DEBUG] [PROXY] Successfully initialized PySide '1.1.2' located in C:\Program Files\Fabric Engine\Python\2.7\PySide\__init__.pyc."

    Is that going to be problematic? I'm assuming it should be pointing to the PySide that comes bundled with the desktop engine, right?

  • 0
    Rob Blau

    Glad that worked for you.

    Too many things fighting for control of that global PYTHONPATH.  :)

    We will be pushing out a fix next week that'll make sure that when the app starts up it pulls in the intended toolkit install and other bundled modules (including PySide).  So yes, that is a potential issue right now, but we've got it in our sights and'll be pushing out a fix soon.  Thanks for letting us know about it!

  • 0
    Mitchell Lotierzo

    Awesome. Thanks.

    One more thing! :) It would be nice to have control over how the versions are sorted for a command. I specified the 'versions' param for my app launcher like "['2012', '2013', '2014']" and it still sets 2014 as the default (the entry with an asterisk). I thought whichever value was first in the list was considered the default?

    Awesome job by the way. I'm loving this new engine so far. 

  • 0
    Rob Blau

    Hi Mitchell,

    Unfortunately right now if you collapse multiple versions into a button the most recent one is the one that'll be the default.  We are going to be updating that to give you more control over the order those commands get collapsed in, but unfortunately that didn't make the initial release of the engine.  For the time being you'd need to separate out 2012 as its own group to separate it from the rest.

    We'll be updating the engine soon and this is one of the higher priority changes to come.

    Glad you're liking it!

  • 0
    David van Heeswijk

    Hey Guys,

    We're using Gnome 3 on some of our newer Linux boxes.
    Under Gnome 2, the Shotgun Desktop icon was visible in the top bar, like under OSX.

    Now on Gnome 3, the icon is in the system tray (hidden in a drawer in the bottom of the screen) which you can acces by pressing command (or windows key) + M. However, we would like the same behaviour like under Gnome 2.

    Is there a way to get the icon back to the top of the screen by default?



  • 0
    Rob Blau

    Hi David,

    The Gnome 3 notification setup definitely leaves a little to be desired.  From what I can tell you need to use a shell extension to be able and use it.  This is the one that seems to do what you'd want:

    although you might want the fork from this repo:

    Does that look like it would work for you?

  • 0
    Patrick Macdonald

    Is it possible to open a project in a pipeline-config clone rather than the primary pipeline-config? 

  • 0
    Patrick Macdonald

    Ah found it, there's a dropdown in the desktop project page providing access to dev environments.

  • 0
    Matthias Wäsch - Celluloid VFX

    Hey Guys,

    how did you get the "combine related commands into submenus" working, showing different Nuke versions in the picture above? If I try customizing the collapse rules, it looks like menu_label don´t understands the token "$version". If I try instead off this, the token "$app", it´s working but kind of senseless this way. So why is $version not working?

    Another Question is, is it possible to create just one launch_nuke entry in app_launchers.yml for different nuke versions Nuke 8 & 9, using the configuration setting "versions:". Their executable files has different names and the path includes build version in the version description.

    nuke8.0_windows: 'C:\Program Files\Nuke8.0v6\Nuke8.0.exe'

    nuke9.0_windows: 'C:\Program Files\Nuke9.0v8\Nuke9.0.exe'

    At the moment I import two entries launchnuke8.0 and launch_nuke9.0 with two different "windows_path"s defined.

    Cheers, Matthias

  • 0
    Rob Blau

    Hi Matthias, for version to work you'd need to have that token in the match portion of the collapse rules like this:

    collapse_rules: [{'menu_label': '$version', 'match': 'Launch $app $version', 'button_label': '$app'}]

    And you can use the syntax described here to collapse down the config for Nuke 8/9:

    So if you have versions set to ["(9.0)v4(beta1)", "(9.0)v3"] then you could use "{v0}" in your paths.

  • 0
    Matthias Wäsch - Celluloid VFX

    Hi Rob,

    thanks for replying!

    At First, the syntax you described for the collapse_rules confused me a bit, because you are using square & curly brackets and all that single quotation marks. I tried this and got errors while launching Shotgun Desktop. But If I keep the syntax for collapse_rules, the project.yml file provides:


    - {button_label: $app, match: Launch $app $version, menu_label: $version}

    Then it´s working fine.

    Great Hint, how to deal with the syntax for the versions! Now I just have one Nuke path defined for several versions and for two entries (one for Nuke and one for NukeX) in the app_launcher.yml.

    Do I need to have two entries there, for the ability to have Nuke and NukeX running? Or maybe is there a way, with only one launch_nuke entry for both abilities?

    I´m wondering why the hint with the syntax for the versions isn't in the official documentation for the Desktop-Engine or Application-Launcher. Especially the screenshot here is showing that is possible, but it's not described how! So Rob, thanks a lot!

    Cheers Matthias


  • 0
    Rob Blau

    Hi Matthias,

    I was surprised to see our lack of docs on this feature too!  I just updated the documentation for how to use the versions setting to include these details.  It'll show up with the next release of the multi launchapp.

    Sorry about that!

  • 0
    Anthony Scudese

    Is it possible to have folder creation and other things in the sg desktop app?

Please sign in to leave a comment.