Installing Shotgun Desktop and creating your first Toolkit Project
Want to see what the Shotgun Pipeline Toolkit is all about? This document explains with simple, step-by-step instructions how to install the Shotgun Desktop and setting up your first Toolkit project.
This document is out of date. You should now download Shotgun Desktop from within Shotgun following the instructions in our user guide.
Information on how to configure Desktop and setup a project has moved to our admin guide.
This document describes how to install and configure Toolkit and Shotgun Desktop. We recommend that you start here when you want to try out Toolkit for the first time. Just follow the instructions step by step, and we'll guide you though setting up Shotgun Desktop and then Toolkit with default settings in a test environment.
Once you have set up your first project, you can try it out, tinker with it, take a closer look to see how it works and understand how it can work with your pipeline. Learn how to make Toolkit create folders and disk and how to set it up work with your studio file naming conventions.
In order to run Shotgun Desktop and the Pipeline Toolkit, you need to have a Shotgun Site up and running. If you don't, please head over here where you can get set up with a free Shotgun trial account.
Downloading Shotgun Desktop
It all starts with the Shotgun Desktop, a software application which extends the Shotgun experience on to your local machine and makes it easy to access Shotgun data, launch applications and run pipeline integration tools directly from your machine. Shotgun Desktop also handles installation and maintenance of Toolkit projects.
Shotgun Desktop comes with a separate installer for Windows, Mac and Linux. Please click the links below to download Shotgun Desktop suitable for your environment:
The links above point to the latest release.
When you have downloaded and installed Shotgun Desktop on your machine, double click to launch the installer! Please note that you may need administrator privileges to install the application on your machine.
Advanced Installation Topics
Configuring the Shotgun Desktop
See the documentation in our Admin Guide for how to configure Shotgun Desktop.
Command line based activation
Before the Shotgun Desktop was introduced as the recommended way to getting started with Toolkit, we had a command line based activation workflow. This workflow is slightly more technical, but can in some cases be relevant, for example if you are having trouble running the Shotgun Desktop's UI environment. In that case, we suggest that you head over to the command line based activation docs:
Existing Shotgun Desktop Pilot Program users
If you are part of our Shotgun Desktop pilot program, and already have a pilot version of Shotgun Desktop installed, you need to uninstall this before you install the official release.
In addition to this, you also need to go to Shotgun, locate and delete the primary pipeline configuration for the Template Project. If you need any help with this, just drop us a line on
If you fail to delete the primary pipeline configuration for the Template Project prior to launching Shotgun Desktop, you will encounter an error that says
Cannot set up this project! Non-auto-path style pipeline configuration entries already exist in Shotgun.
Detailed System Requirements
The following operating system platforms are currently supported:
- Windows XP/Vista/7/8/10
- macOS 10.6+
- Linux 64 bit CentOS 5/6, and Fedora 15+ (separate installers)
For the CentOS 5/6 installer, the following libraries are required to be installed on the target machine:
- On some versions,
compat-readline5is also required (64 bit).
For the Fedora installer, the following libraries are required to be installed on the target machine:
On Linux, the executable is located here after install:
What if you already have Toolkit set up in your Studio?
If you already have Toolkit running in your studio, Shotgun Desktop will not change any of your existing workflows. It will read your existing pipeline configurations and when you click on a project in the project overview, it will try to load the project environment for that project and then start the desktop engine. If the desktop engine isn't found, you can click a button and Shotgun Desktop will automatically copy your existing Shotgun action menu items and use those entries to create a desktop engine configuration.
How does the desktop install process work exactly? Will it affect my existing setup?
Shotgun Desktop will not make any changes to any existing project configurations or other setup items without your consent. After you have installed it, started it up, and logged on with your normal Shotgun user name and password, Shotgun Desktop will create what we call a site configuration. This is a new type of pipeline configuration which isn't associated with a particular project, but instead represents the entire site, with all its projects. You can see this site configuration in the form of a pipeline configuration entry which is associated with the default template project. Also please note that by default, this pipeline configuration has got blank path entries. This means that the configuration runs in a new auto path mode, where it doesn't need to reside on a particular location on disk. Instead, Shotgun Desktop will manage the location of the site config and install it automatically for you on your local machine.
This site configuration does not need to be maintained like a normal project (using the
tank core commands). This would not be practical, since there is a site configuration on each
local machine which has Shotgun Desktop installed. Instead, is updated automatically
every time you start up Shotgun Desktop, ensuring that all users are running the same (latest) version.
Please note that it is perfectly possible to change the behavior of this site configuration to behave exactly like a normal project. Simply add path entries to the site pipeline configuration in Shotgun and move your local site configuration into this location and this configuration will behave just like any other project. Once you have specifically set the path to the site config, the automatic updates will also stop.
It is also possible to specify a site configuration root path in an environment variable TK_SITE_CONFIG_ROOT. This is a good way to test out changes to the site configuration prior to release. Note, however, that
install_location.yml must be updated with the path of the specified config for the configuration to be actually used.
Having trouble getting started?
If you are having issues installing Toolkit or the Shotgun Desktop, don't worry! We are here to help! Toolkit can be a complex system and we are happy to help guide you through advanced setups or just lend a hand if you are not sure what to do. Here are some pointers:
- If you are running a locally hosted Shotgun or using a proxy server, please see the advanced section above for advice and options.
- If you are interested in setting up Perforce or the games configuration, additional steps beyond the installation are necessary. Please contact us and we'll be happy to help out!
- If you are running into problems with the Shotgun Desktop and would prefer to use the old command line based Toolkit activation, you can find detailed instructions here:
As always, if you have any questions or need any help, never hesitate to reach out to us on firstname.lastname@example.org. We'll be happy to help out and guide you through the process.
Running Shotgun Desktop for the first time
When you launch Shotgun Desktop for the first time, it will ask you to log on to your site.
Note! The very first time you log into Desktop for a Shotgun site and any time you are setting up a Project, make sure that the user that you are logging in as has administrator privileges, otherwise some of the setup steps cannot be carried out.
Now Shotgun Desktop will prompt you to jump to the App Preferences and turn on Toolkit if you haven't already done so.
Once Toolkit has been turned on, Shotgun Desktop will initialize itself and after a brief delay, you will see an overview of all your Shotgun projects. Now, if you click into a project, you can proceed directly to the Toolkit project setup wizard by clicking the "Set up Project" button.