Configuration Overview

While AWS credentials are handled separately, psiTurk reads configuration settings from the following three places, and in the following order, with former entries being preferred over later ones.

  1. Environment variables, optionally specified in a .env file.
  2. A config.txt file (i.e., user-specified defaults)
  3. A .psiturkconfig file
  4. psiTurk defaults

That is to say, (4) there exist psiTurk-set defaults for many settings, (3) but a user may specify preferred defaults in a config.txt file, which they may override in turn via a ~/.psiturkconfig file, with (1) environment variables superseding any previous setting.

Furthermore, psiTurk loads and uses the python-dotenv library, which means that, on platforms that respect it, you can store KEY=VALUE pairs in a file called .env in your project’s root directory, and they will be read in as environment variables by psiTurk.

Which go where? Consider security and privacy, as well as science replicability

While any setting can be set via environment variables, only some make sense to do so. For instance, configuration settings that are credentials-related should not be saved to source code repositories, from whence they may leak. Instead, they can be set via environment variables. Sensitive settings include the following:

In other instances, a different setting may be desired for “development” environments than in “production” ones. For example, local development may want to use one database, while a psiturk experiment deployed onto a cloud hosting service for “live” data collection may want to use a different database. Or, different server host, port, and threads settings may be desired. Other settings can enable or disable dashboard and task-runner features, which may only be desirable for certain deployments. Environment variables are ideal for situations like these, rather than committing them to a static configuration file.

However, most other settings are best stored where they can be shared with others, for science replication purposes. Such settings should go in config.txt.

Additionally, a user may set any available setting to a global preferred value in a file called ~/.psiturkconfig.

Finally, many – but not all – settings have psiturk-set defaults. Look in an example config.txt file generated by the psiturk-setup-example, and on the settings page within these docs, for documentation on the different settings and their defaults.


In general, changes made to configuration settings require restarting the server process as it may change the behavior. Generally it is best to edit these files while psiturk is not running, and then restart the server.

Local configuration file

A sample default local configuration file can be viewed on github here. A copy of this file is placed in the example directory as part of running the psiturk-setup-example command. In order for changes to config.txt to be read by psiturk, this file must be placed in the root of the psiturk study directory.

See Settings for descriptions of the available configuration parameters.

The .psiturkconfig global config file

Any configuration option can actually be placed in either the global or local configuration file. For example, if you wanted to run different project from different AWS accounts, you could add an [AWS access] section to move the local config.txt files and have different values in different folders. And vice-versa – any setting could be placed in the .psiturkconfig file in lieu of in config.txt.

By default, .psiturkconfig is searched for in the user’s home directory ( ~/.psiturkconfig), but the search location can be customized by setting the PSITURK_GLOBAL_CONFIG_LOCATION environment variable. This env var cannot be set via the .env file – rather, it must be available in the shell environment).


Keep in mind that settings in the local config.txt file always override settings in the global .psiturkconfig file. In turn, environment variables always override all other config settings.