Getting psiTurk Installed on Your Computer¶
psiTurk can be installed on any modern computer which supports Python (<= 2.7). However, currently psiTurk is not supported on Windows (see below). It works well on most unix variants including Mac OS X, BSD, and Linux. Installation is usually not difficult.
When psiTurk is successfully installed, you will simply have a new
command line tool available called
provides a number of functions to you including launching the server
and interacting with the Mechanical Turk and Amazon Web Services (AWS)
Installation of psiTurk requires:
- A python installation (<= v2.7). We recommend the Enthought python distribution on Mac OS X.
- The ``pip`` package manager. Directions on installing this are given below.
- Access to a command line tool. (e.g., Terminal.app on Mac OS X)
- A web browser. A WebKit compatible browser such as FireFox, Safari, or Chrome is recommended.
An additional requirement for actually using psiTurk to run experiments is an Internet connected computer capable of receiving incoming requests.
To install the package there are two options currently. First, the
current stable release of psiTurk is hosted on the python package
index pypi. As a result, it can
easily be installed as a standard python package using the python
package manager tool
pip. Alternatively, you can install directly
from the development branch on
github. The following
instructions describe the general process. In addition, system specific
notes are provided below.
Install stable version via pypi¶
The easiest way to install psiTurk is via
pip. Linux users will
likely prefer to install pip as described below.
Otherwise, If you don’t already have
pip, you can install it by
typing the following in a terminal:
cd /tmp # Just to put us in a directory that will be cleaned up periodically curl -O https://raw.githubusercontent.com/pypa/pip/develop/contrib/get-pip.py python get-pip.py # If you get a permissions error, try typing sudo python get-pip.py
If you want a single system to run different versions of psiTurk (or other python packages) on a per-experiment basis, follow the Virtual Environment instructions below.
pip is installed, type into a terminal:
pip install psiturk
If this doesn’t work, try
sudo pip install psiturk
If the install was successful you will have a new command
available on your command line. You can check the location of this
command by typing
Install directly from github¶
You can also install the bleeding-edge development version directly
from github using
pip. To install the latest stable branch follow
the instructions above to install
sudo pip install git+git://github.com/NYUCCL/psiTurk.git@master
If the install was successful you will have a new command
available on your command line. You can check the location of this command
Updating from a previous version¶
To avoid compatibility issues, if you upgrade from a previous version it can be useful to first uninstall then reinstall psiTurk using the following sequence of commands:
$ pip uninstall psiturk $ git clone email@example.com:NYUCCL/psiTurk.git $ cd psiTurk $ sudo python setup.py install
Running inside a Virtual Environment¶
It can desirable to keep each of your experiments’ dependencies (python and python package versions) isolated from each other. For example, if you want to install the development version of psiTurk (as described above) in one experiment, but not all the others installed on your system, Virtual Environments provide a solution.
You can install via pip:
sudo pip install virtualenv virtualenvwrapper
And then start a new shell session. This will install the virtualenv tool as well as the supplementary virtualenvwrapper tools that make working with virtualenvs easier. You create a virtual environment as follows (if mkvirtualenv is not recognized follow the instructions here) :
$ mkvirtualenv my-experiment Running virtualenv with interpreter /usr/bin/python2 New python executable in my-experiment/bin/python2 Also creating executable in my-experiment/bin/python Installing setuptools, pip...done.
Then, at any point in the future, to activate the virtual environment use the workon command
$ workon my-experiment (my-experiment) $ which python python pip easy_install ~/.virtualenvs/my-experiment/bin/python ~/.virtualenvs/my-experiment/bin/pip ~/.virtualenvs/my-experiment/bin/easy_install
As you can see, when the environment is active, running python or pip will run copies specific to your project. Any packages installed with pip or easy_install will be installed inside your my-experiment virtualenv rather than system-wide. Use the deactivate command to leave the virtualenv.
Mac OS X¶
Apple users will need to install a C compiler via XCode; to do so, install XCode from the App store. Once you have downloaded it, install the command line tools from the preferences menu as instructed here. For earlier versions of Mac OS X (e.g., Snow Leopard) you may need to install XCode using the installation disc that came with your computer. The command line tools are an option during the installation process for these systems.
psiTurk is relatively painless to install on most Linux systems since all four of the requirements listed above come installed by default in most distributions.
If you encounter install problems when installing using pip as above, a likely cause is that you are missing the package from your distribution that contains a needed header file. In this case, one way to troubleshoot the problem is to do a web search for the name of your distribution and the name of the missing header file (which often appears in the error text produced by a failed pip install). That search will likely turn up the name of the package for your distribution that supplies the needed header file.
As an example, before installing psiTurk on a minimal Debian 7 server (such as the one provided by many server hosting companies) you will need to install some additional packages, as illustrated by the following example command:
aptitude install python-pip python-dev libncurses-dev
If you would like to use mysql as your backend database (which is optional, and can be done at any time), further packages are needed. On a Debian system, they are:
aptitude install python-pymysql python-sqlalchemy libmysqlclient-dev
If you have additional specific issues, or if you can report the steps needed to install psiTurk on a particular Linux distribution, please help us update the documentation!
psiTurk is currently not supported on Windows. This is due to a technical limitation in the ability to run server processes on Windows. However, there are a number of options to get around this (see below for details on each option):
Cloud-based install (experimental)¶
If your local computer does not support psiTurk is it still possible to use the package by using a free hosting solution such as openshift. Begin by creating an account at http://openshift.redhat.com/ and download the command line tools at https://www.openshift.com/developers/rhc-client-tools-install
Create a python-2.7 application and add a PostgreSQL cartridge to the app
rhc app create psiturk python-2.7 postgresql-8.4 --from-code git://github.com/jbmartin/psiturk-on-openshift.git
or you can do this to watch the build
rhc app create -a psiturk -t python-2.7 rhc cartridge add -a psiturk20 postgresql-8.4
Add this upstream psiturk repo
cd psiturk git remote add upstream -m master https://github.com/jbmartin/psiturk-on-openshift.git git pull -s recursive -X theirs upstream master
Then push the repo upstream
That’s it, you can now checkout your application at
To access the your openshift hosted database run
rhc port forward -a psiturk
Connect to the database using your favorite SQL app, the PostgreSQL Local specs, and your credentials.
You can install a program like VirtualBox on your pc. Programs like these are called hypervisors and emulate a computer within your computer. Your physical machine is called a host and the virtual machine is called a guest. This technique allows you to install a Linux guest regardless of what OS the host is running.
Virtualization requires some computing power from the host so this option is not recommended if your psiturk experiment requires a lot of computing power as well or if it’s is expected to have a lot of participants active at once. However, it is a good option to develop and test your psiturk experiments on Windows systems prior to Windows 10. If you are running Windows 10 or higher see below for the WSL option, which is much easier on your system than virtualization.
After you install the virtual machine software you need an installation image for a Linux based OS. You can choose any Linux distribution you like but Ubuntu is a good choice if you don’t know which one to pick. You can usually obtain an *.iso file for the Linux distribution you like. These are virtual cd-roms. You can load them into your virtual machine and begin installing the guest OS. Once that is complete you boot your virtual machine into Linux and follow the installation steps for Linux.
Windows Subsystem for Linux (WSL)¶
Windows now has the option to run a Linux translation layer inside Windows (WSL 1) or even a full Linux kernel (WSL 2). Either will allow you to run psiturk within the Linux subsystem. See https://docs.microsoft.com/en-us/windows/wsl/install-win10 for instructions on how to activate WSL on your system.
After you activate WSL and install a Linux distribution of choice as described you must make a small change to
its configuration and install one or two libraries. Within the WSL environment create or edit the file
If you don’t know how to edit a file within WSL just run:
sudo nano /etc/wsl.conf
You will need to edit the file with admin rights (the
sudo part of the command) which requires your WSL admin
password. You chose the password when you installed WSL. This is a different password from your Windows admin
or Windows user password! Add these contents to the file:
[automount] options = "metadata"
If you used
nano press control + X to exit. Nano will ask you to save the file. Choose Y for yes and exit.
Editing this file enables file permissions to work as they do in Linux. This is needed
when psiturk tries to read
~/.psiturkconfig. After you’re done editing
wsl.conf exit all WSL windows and
start a new one.
Most Linux distributions come with many libraries pre-installed, but WSL omits many of them. In a WSL window run these commands
sudo apt-get install libncurses5-dev sudo apt-get install libpq-dev
The first one is needed for psiturk. The second one is optional and is only needed if you use a database other than sqlite. Run these commands next in a WSL window:
pip3 install psiturk pip3 install psycopg2
If you get an error saying
Command 'pip3' not found try replacing it with
pip. If that still doesn’t work
sudo apt-get install python3 python3-pip. The first pip3 command installs psiturk itself. The second one is optional
and again is only used if you use any database other than sqlite. Finally, create a file called
You can use
nano or any other text editor. You can enter your AWS and psiTurk access keys now or edit this
file later. After you have created the file run this command
sudo chmod +rw ~/.psiturkconfig
This makes sure psiTurk is allowed to read the file. If you forget this step psiTurk will tell you the key is invalid but it really means it couldn’t read your config file. You only have to run this command once however, so if you’re sure you did it or just ran it again to be sure and psiTurk still tells you the keys are invalid then the keys really are invalid.
You should now be able to run psiTurk in the WSL environment. The status line will look a bit different since WSL doesn’t draw some box art characters properly but psiTurk will work just fine.