Installing PsyNet via virtualenv (Linux)

The following installation instructions are tested with Ubuntu 22.04 LTS (Jammy Jellyfish). They address both experiment authors as well as developers who want to work on PsyNet’s source code.

One-time setup

The following steps need to performed each time you setup a new computer to run PsyNet experiments.

Check Linux version

The following installation instructions are tested with Ubuntu 20.04 LTS (Focal Fossa). You may wish to check that you have an up-to-date version of Linux before proceeding.

Update and install required system packages

sudo apt update
sudo apt upgrade
sudo apt install vim python3.11-dev python3.11-venv python3-pip redis-server git libenchant-2-2 postgresql postgresql-contrib libpq-dev unzip

Install Python

PsyNet requires a recent version of Python 3. To check the minimum and recommended versions of Python, look at PsyNet’s pyproject.toml file, specifically at the line beginning with requires-python. To see the current version of Python 3 on your system, enter python3 --version in your terminal. If your current version is lower than the minimum version, you should update your Python to the recommended version. The easiest way to do this is via the apt install command above, for example sudo apt install python3.11-dev for Python 3.11.

Install Docker and Docker plugins

sudo apt install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
   "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] \
   "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install docker-compose-plugin docker-buildx-plugin

Install Google Chrome

wget -q -O - | sudo apt-key add -
sudo sh -c 'echo "deb [arch=amd64] stable main" >> /etc/apt/sources.list.d/google-chrome.list'
sudo apt update
sudo apt install google-chrome-stable

Setup PostgreSQL

sudo service postgresql start
sudo -u postgres -i
createuser -P dallinger --createdb

Password: dallinger

createdb -O dallinger dallinger
createdb -O dallinger dallinger-import
sudo service postgresql reload

Install heroku client

curl | sh

Download the PsyNet repository

Downloading the PsyNet repository is not strictly necessary, but it is useful to be able to look at the source code, as well as to access the collection of demos it provides.

We recommend downloading PsyNet to your home directory if possible, there are some PsyNet features that run smoother if it is located there.

git clone

You can then find the PsyNet demos within the demos directory.

By default this will download the latest version of PsyNet’s master branch, but new versions are released regularly. To get the latest version, run the following:

cd ~/PsyNet
git pull

If you want to ensure that this version of PsyNet is exactly the same as the one that your experiment will use, you can check out a specific version of PsyNet like this:

cd ~/PsyNet
git checkout v10.4.0

where 10.4.0 matches the PsyNet version number specified in the experiment’s requirements.txt file.

Installing virtualenv

You need to use virtual environments to work with PsyNet. This can be confusing if you haven’t used Python virtual environments before. We strongly recommend you take half an hour at this point to read some online tutorials about virtual environments and managing them with virtualenvwrapper before continuing.

The following code installs virtualenvwrapper:

pip3 install virtualenv
pip3 install virtualenvwrapper
export WORKON_HOME=$HOME/.virtualenvs
mkdir -p $WORKON_HOME
export VIRTUALENVWRAPPER_PYTHON=$(which python3)
source $(which
echo "export VIRTUALENVWRAPPER_PYTHON=$(which python3)" >> ~/.zshrc  # If you are on Linux, you may need to replace ~/.zshrc with ~/.bashrc
echo "source $(which" >> ~/.zshrc  # If you are on Linux, you may need to replace ~/.zshrc with ~/.bashrc

If you are interested in contributing to PsyNet, you should also complete the Additional developer installation steps.

Setting up a new project

The following steps need to be performed each time you start a new project.

The first step is to identify which project you want to set up. A PsyNet project is identified with an ‘experiment directory’, which is a folder containing various standardized files defining an experiment implementation, most importantly an file and a requirements.txt file. If you are exploring PsyNet for the first time, we recommend that you start with one of the demo experiments, which can be found in the demos folder of the PsyNet repository. Alternatively, you can download one of the example experiments listed on the PsyNet website. If you are planning to create your own experiment, you can start by copying one of the demo experiments to a new directory and modifying it as appropriate.

To open a project in PyCharm (e.g. a demo), click ‘Open’ in the PyCharm welcome screen, then navigate to the directory containing the project, select the project, and click ‘Open’. Alternatively, if you already have a PyCharm project open, click ‘File’ > ‘Open’, find the directory, select it, and click ‘Open’.

When you open a new project in PyCharm, you should see a dialogue box that says something like “File requirements.txt contains project dependencies. Would you like to create a virtual environment using it?”. In the dependencies field you should see a path ending in requirements.txt. Replace “requirements.txt” with “constraints.txt” and then click “OK”. PyCharm will then create a virtual environment for you and install all the required packages.


This workflow uses virtualenv to create an isolated virtual environment for each project. PyCharm remembers which virtual environment to use for each project, and will load it automatically when you open the project.


If you are not using PyCharm, you can install the required packages using the following command:

pip install -r constraints.txt


Why do we install from constraints.txt rather than requirements.txt? requirements.txt is written manually by the experimenter, and lists all the packages that they want to use in their experiment. constraints.txt is then automatically generated by PsyNet, and additionally lists all the dependencies of the packages in requirements.txt. Importantly, PsyNet ensures that the versions of the packages in constraints.txt are compatible with the current version of PsyNet. Moreover, listing these versions explicitly in constraints.txt means that when future experimenters come to run the experiment, they will be able to install exactly the same versions of the packages that we originally used.

If you do not see this PyCharm dialogue box, you can instead create the virtual environment by clicking the interpreter box in the bottom right corner of the screen (it might say something like ‘No interpreter selected’ or ‘Python 3.X’), then clicking ‘Add new interpreter’ > ‘Add local interpreter’. Select ‘Virtualenv environment’, select ‘New’, make sure that the correct version of Python is selected, then press OK. PyCharm will spend some time processing this selection, but then when you open a new terminal tab it should load your virtual environment automatically.

If you are working as a PsyNet developer, now is the moment to install PsyNet and Dallinger in development mode. To do this, run the following commands (assuming you have installed PsyNet and Dallinger in the default locations):

pip install -e ~/PsyNet
pip install -e ~/Dallinger

Whenever you develop or deploy an experiment using PsyNet (assuming you are not using Docker) you will need to make sure you are in the appropriate virtual environment. You can confirm that you are in the correct virtual environment by looking at the start of your terminal prompt. It should look something like this: (my-project) your-name@your-computer-name ~ %. If you have only just created your new virtual environment in PyCharm, you might need to open a new terminal window for your virtual environment to be loaded. Your virtual environment should activate automatically when you open your project in PyCharm; if it does not, you can select it by clicking the interpreter box in the bottom right corner of the screen.

Once PyCharm has finished installing the required packages, you should be able to run the experiment with the following command:

psynet debug local


If you are not using PyCharm, you can create a virtual environment using the following command:

mkvirtualenv my-project --python $(which python3)

where in this case my-project is the name of the virtual environment.

You can activate your virtual environment by running the following command:

workon my-project

You can then delete your virtual environment by running the following command:

rmvirtualenv my-project


If you experience problems setting up the virtual environment:

  • Check in which directory is installed. This might be a different directory than ‘~/.local/bin/’. In that case, adapt the code above to source this file accordingly.

  • Check whether the directory where was installed is added to PATH. If not, add the directory to PATH.