When Toolkit bootstraps, what order is used to determine the correct PipelineConfiguration entity?

A question I’ve seen asked a few times is if you have a Project and you view it in Shotgun Desktop, which PipelineConfiguration will it use by default when there are multiple defined in Shotgun?

The rules for bootstrapping and automatically selecting a PipelineConfiguration are listed:

  1. Project Config ( project field matches the current Project that’s being bootstrapped).
    a. Dev/sandbox* with the lowest ID
    b. named “Primary”

  2. Site config (no project defined)
    a. Dev/sandbox* with the lowest ID
    b. named “Primary” (edited)

  3. If no config is defined then it falls back on a base config fallback, hardcoded in the plugin, will be used. (In the bootstrap API, this is defined via the base_configuration() property).

*Dev or Sandbox config is a config not called “Primary”.
Configs are also filtered by PipelineConfiguration entity’s user restrictions field and plugin ids field.

This info can also be found here.

However SG Desktop has further selection requirements:

SG Desktop Project Specific Rules

Shotgun Desktop allows you to switch between Project configs in the UI, so the order is less of an issue here if you are not using site configs.

The first time you enter a project in SG Desktop, it will select a config named Primary as the default config, if there is no Primary config, it will pick the first config found in alphabetical order.

Also Shotgun Desktop will remember the configuration you picked last, so if in one session you change the config you were using on a particular project, then it will use that config next time you enter that project in SG Desktop.

Changing the config for a project in Shotgun Desktop does not affect any toolkit usage outside of SG Desktop, for example, any scripts, browser integration, or Shotgun Create. It will only affect the software and apps that you launch from SG Desktop.


Thanks a lot for writing this up! Posts of this sort are really useful.
One question - is there a toolkit utility function for this automatic selection of pipeline config?
A lot of our scripts run outside shotgun desktop, and handle this stuff explicitly.
Alas, I’m not very well acquainted with the utility framework yet.


If you are using the bootstrap API and don’t specifically specify a PipelineConfiguration then it will use the order/rules mentioned above for picking the configuration.

You can also ask the bootstrap API to return the available PipelineConfigurations with get_pipeline_configurations().


Oh cool, I need to start using this. Currently doing the whole manual dance of sg.find("PipelineConfiguration", [["project"...]], then adding the path to sys.path and loading sgtk :blush:
In fact, we already have some small abstractions for this, so deleting code would be awesome!


I recently released a guide on bootstrapping as well, which might be helpful.


Just a headsup on this. I recently had an odd situation whereby when I opened Publisher2 it used a different pipeline config in the background worker thread to the one I was using at the time. The odd thing being that the config it chose actually had a user-restriction applied that should have caused it to be filtered out.
I eventually narrowed down the cause of this to either having filesystem location entities connected to old pipeline configs (via the pipeline-configuration field) and/or the local caches held in your %appdata%/shotgun/ folder.
I’ve raised a ticket about this as a possible bug, but thought I’d post it here in case anyone else stumbles across this odd behaviour.
The only reason I noticed this problem is that I was setting a critical environment variable in the tank_init hook, whch gets executed when Publisher2 GUI Opens.


Hey @Patrick , I can take a look, I think the ticket you are referring to is the one around sgtk_from_path. This is not using bootstrap API, so the rules there are different. sgtk_from_path with distributed configs doesn’t make as much sense and we tend to avoid it, it’s more useful for centralized configs. But it doesn’t sound like you were trying to instigate that call, and it’s coming from one of our apps, so maybe you’re hitting a bug, I’ll look at it more.


Thanks Phil!

1 Like