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 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
If your studio is using a proxy server, if you want to pre-populate the initial login screen with some values, or if you want to tweak how the browser based application launcher integrates with the Shotgun Desktop, there is a special configuration file called
The file is searched for in multiple locations and in the following order:
- An environment variable named
SGTK_PREFERENCES_LOCATIONthat points to a file.
- An environment variable named
SGTK_DESKTOP_CONFIG_LOCATIONthat points to a file. (deprecated)
- Inside the Shotgun Toolkit preferences file.
- Inside the Shotgun Desktop preferences file. (deprecated)
The Shotgun Toolkit preferences file is located at:
The Shotgun Desktop preferences file is located at:
If you wish to store your configuration file somewhere else on your computer or on your network, you can set the
SGTK_PREFERENCES_LOCATION environment variable and then launch the Shotgun Desktop.
A fifth, but deprecated option is to store the configuration file inside the installation folder on Windows and Linux. On macOS, it is a bit tricky and the file needs to be added to the application bundle, in the following location:
Note that storing the configuration file inside the application bundle is not recommended on macOS. Adding a file in that location invalidates the package's digital signature. Such a package will be flagged as altered by macOS and security prompts will appear during the execution of the application, notably to allow communications to go through the firewall.
You can see a documented example of a configuration file here
Please note that you can use environment variables as well as
hard coded values in this file, so that you could for example pick up the default user name to suggest to a user via the
USERNAME variable that exists on Windows.
Running Shotgun Desktop with a locally hosted site
If your Shotgun site url does not end with
shotgunstudio.com, it means that you are running a local Shotgun site. In this case, it is possible that your site has not yet been fully prepared for Toolkit and the Shotgun team may need to go in and do some small adjustments before you can get going! In this case, please drop us a line on
firstname.lastname@example.org and we'll help sort you out.
Connecting to the Toolkit app store with a locally hosted site
If you are using a local Shotgun site with access to the Internet through a proxy, you might want to set an http proxy for accessing the Toolkit app store, but not the local Shotgun website. To do this, simply add
app_store_http_proxy: <proxy_server_address> to
<proxy_server_address> is a string that follows the convention documented here.
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 email@example.com. 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.
The Toolkit Project setup wizard
Setting up a new project in Toolkit is now quick and straight forward thanks to the Shotgun Desktop project wizard. It will take you through a step by step process and at the end you have a fully working Toolkit project, ready to be used. Each section below explains in detail each of the steps of the wizard with examples and suggestions of sensible default values in case you are not sure how to set things up. Note that you can reach the sections below by pressing the help button on the various wizard UI screens.
Select a configuration type
When you start configuring a new project, the first thing to decide is which configuration template to use. A configuration template is essentially the complete project configuration with all settings, file system templates, apps and logic needed to run the project.
- If this is your very first project, head over to the Shotgun defaults to get you started.
- If you already have configured projects and configurations for previous projects, you can easily reuse these by basing your new project on an existing project
- For advanced workflows, you can use external configurations or configs stored in git repositories.
Default configuration templates
This is the place to go if you want to start from scratch. The various Shotgun default configurations contain all the latest apps and engines set up with a default file structure and file naming convention.
Typically, once you have installed the default configuration, you need to go in and tweak the config and adjust it to work with your pipeline, your application paths etc. Once you have got a project up and running, you can base your next project on this project, and keep going and evolving your studio configuration that way.
Basing your new project on an existing project
This is a quick and convenient way to get up and running with a new project with all the defaults and settings that you had in a previous project. Toolkit will simply copy across the configuration from your old setup to the new project. This is a simple and pragmatic way to evolve your configuration - each new project is based on an older project.
For more ways and documentation on how to evolve and maintain your pipeline configuration, see here:
Using a configuration template from git
Use this option if you want to keep your project's configuration
connected to source control. Specify a url to a remote git or github repository and the setup process will clone it for you.
Note that this is not just github, but works with any git repository. Just make sure that the path to the repository ends with
.git, and Toolkit will try to process it as a git setup. Because your project configuration is a git repository, you can
commit and push any changes you make to your master repository
and beyond that to other projects. Using a github based configuration makes it easy to keep multiple
Toolkit projects in sync. You can read more about it here:
Please note that if you are running on Windows, you need to have git installed on your machine and accessible in your
PATH. On Linux and Mac OS X, it is usually installed by default.
Browsing for a configuration template
Use this option if you have a configuration on disk, either as a folder or zipped up as a zip file. This can be useful if someone has emailed a configuration to you or if you keep a master config on disk which you are basing all your projects on. This is usually an expert option and we recommend either using a config from another project or one of our app store default configs.
Setting up a storage
Each Toolkit project writes all its files and data to one or more shared storage locations on disk. For example, a configuration may require one storage where it keeps textures, one where it keeps renders and one where it stores scene files. The main project storage is always called primary.
Normally, these storages are controlled from within the Shotgun Site Preferences, under the File Management tab. The Toolkit Setup wizard will check to make sure all the different storages that the configuration needs have been set up properly. If they are missing or don't have a path set for the current operating system, you will be prompted to enter values.
Once the project is being set up, Toolkit will create a folder for each new project in each of the storage locations. For example, if your primary storage location is
/mnt/projects, a project called The Edwardian Cry would end up in
/mnt/projects/the_edwardian_cry. And if the config is using more than just the primary storage, each of the storages would end up with an
Your primary storage location is typically something like
\\studio\projects and is typically a location where you are already storing project data, grouped by projects. It is almost always on a shared network storage.
Choosing a project folder name
Now it is time to choose a disk name for your project. This folder will be created in all the different storages which are needed by the configuration. You can see a quick preview in the UI - for most configurations this will only preview the primary storage, but if you are using a multi root config, additional storages will show up too. Toolkit will suggest a default project name based on the name in Shotgun. Feel free to adjust it in order to create what is right for your setup.
Selecting a configuration location
Lastly, please decide where to put your configuration files on disk. Toolkit will suggest a location based on previous projects, so that they all end up in the same place on disk.
The configuration normally resides on a shared storage or disk, so that it can be accessed by all users in the studio who needs it. If you are planning on using more than one operating system for this project, make sure to enter all the necessary paths. All paths should represent the same location on disk. Often, the path can be the same on Mac OS X and Linux but will be different on Windows.
If this is your first project, you typically want to
identify a shared area on disk where you store all your future pipeline configurations. This is typically a location where you store software or software settings shared across the studio. This could be something like
/mnt/software/shotgun. It may vary depending on your studio network and file naming conventions.
When you set up your first configuration, set it up with paths for all the platforms you use in your studio. This will make it easier later on to create an environment which is accessible from all machines. As a hypothetical example, if your project name is Golden Circle you may type in the following three paths:
linux: /mnt/software/shotgun/golden_circle macosx: /servers/production/software/shotgun/golden_circle windows: \\prod\software\shotgun\golden_circle
Where do I go now?
Once you are up and running with your first project, please navigate to our 'next steps' documentation to learn more about how to configure and adjust Toolkit to better suite your studio needs:
If you want to watch some of our Toolkit screencasts, head over to the videos section:
- A bug fix version of PySide is distributed with Shotgun Desktop and is available here.
- Big Buck Bunny - footage courtesy of (CC) Blender Foundation, www.blender.org