Introduction

PsychoPy is an open-source, Python based software package used for creating behavioral experiments. It features and easy to use graphical user interface. PsychoPy can be used for online research in combination with Pavlovia.

General Information

Table below is clickable to enlarge, filter or sort.
Click here to see the master table.
Filters applied by default (Name=PsychoPy), to see the entire table, click on it and press reset.

Availability, support and advice

PsychoPy comes preinstalled on labcomputers in the FSW (see the Lab PC Software List to check which version). PsychoPy can be requested for work PC's via the ISSC Helpdesk. For unmanaged/personal computers PsychoPy can be downloaded here. SOLO provides only very limited basic support for PsychoPy.

Markers

To send markers with PsychoPy using the UsbParMarker or EVA, the python_markers library can be used, see Github: solo-fsw/python-markers. To use the python_markers library, place the python_markers folder in the same location as your PsychoPy task, and implement the code as described in example.py in your task. The python_markers folder can be downloaded by downloading or cloning the python_markers repo.

Eye Tracking

The necessary plugins or libraries for eye tracking can be installed in the PsychoPy builder when going to Tools > Plugin/packages manager. More information about incorporating eye tracking in your PsychoPy experiment can be found here: Communicating with an Eyetracker — PsychoPy v2024.2.4, but note that these are general instructions. More information on Tobii and EyeLink can be found below.

Tobii

There are different plugin/libraries available for communicating with Tobii, see below.

Using the Tobii Eyetracker Support Plugin

To integrate eye tracking in your experiment with the Tobii Eyetracker Support plugin, follow the information that is provided here: Communicating with an Eyetracker — PsychoPy v2024.2.4. Note that this plugin does not work in all versions of PsychoPy. When you are using a Tobii eye tracker that is supported by the Tobii SDK 2.0, such as the Fusion or Spark (see Supported eye trackers - Tobii Pro SDK documentation), version 2024.2.5 of PsychoPy seems to work without issues.

When you are using an older model, such as the X3-120 or X2-60, version 2022.2.5 of PsychoPy seems to work without issues. You can run this version from a newer version of PsychoPy:

• Make sure that in the current version of PsychoPy the Tobii plugin is installed. Go to Tools > Plugin/packages manager > install the Tobii Eyetracker Support (psychopy-eyetracker-tobii) plugin
• Run your task in PsychoPy version 2022.2.5. Go to the properties of the task and select 2022.2.5 at Use PsychoPy version.

Note that the Validation object does not seem to work in PsychoPy 2022.2.5.

Using the Titta Library

An alternative to using the standard Tobii Eyetracker Support plugin, is the Titta library. This library works very well with both the newer Tobii eye trackers (Fusion, Spark) and discontinued Tobii eye trackers (X3-120, X2-60) in different versions of PsychoPy. See for more information marcus-nystrom/Titta and see marcus-nystrom/Titta - demo experiments for a demo PsychoPy task. The Titta library is used only in code, it does not feature PsychoPy builder objects. Titta also offers an integration with Tobii Pro Lab in External Presenter mode.

To install the Titta library in the PsychoPy builder, go to Tools > Plugin/packages manager > go to the Packages tab and click on Open PIP Terminal. Here, run pip install titta. If Titta is already installed, but needs to be updated, run pip install --upgrade titta.

When you use Titta, make sure to cite it accordingly, see marcus-nystrom/Titta.

The Titta library also provides examples for analyzing the gaze data (.h5 files). Make sure to follow the sample task and test out the whole analysis before starting data collection.

For analyzing pupil data, the PhysioData Toolbox can be used. The File Converter's Eye-Tracking TSV File Converter can be used to convert tsv data files to PhysioData files. Note that this will first require the conversion of the h5 files to tsv files.

Using the Tobii SDK with PsychoPy in code

When you use Python with the PsychoPy library to create your task, you can use Titta (see above) or use the Tobii Pro SDK directly to communicate with your Tobii eye tracker: Free software development kit for eye trackers - Tobii.

When you are using a Tobii eye tracker that is supported by the Tobii SDK 2.0, such as the Fusion or Spark (see Supported eye trackers - Tobii Pro SDK documentation), you should use the SDK provided here: Tobii Pro SDK Downloads.

When you are using an older model, such as the X3-120 or X2-60, you should use version 1.11 of the SDK, which is provided here: How do I work with the new Tobii Pro SDK and Tobii Pro Eye Tracker Manager?.

Documentation can be found here: Python - SDK reference guide - Tobii Pro SDK documentation, make sure to select the correct version.

EyeLink

In general, make sure the EyeLink is connected properly to the Stimulus PC and that network communication configured (see How do I configure my network settings to connect to the EyeLink Host PC?), and that the EyeLink Developers Kit is installed (see EyeLink Developers Kit / API Downloads (Windows, macOS, Linux)). To arrange this on SSH lab PCs, please contact labsupport@fsw.leidenuniv.nl. 

When incorporating EyeLink eye tracking in a PsychoPy task, follow the installation instructions here: Getting Started with PsychoPy / EyeLink Integration (create an SR research account to view the thread). EyeLink communication is achieved through code, or with an EyeLink plugin that has PsychoPy GUI components.

To use only code to communicate with EyeLink, see also the following video: PsychoPy Integration for EyeLink Eye Trackers.

To use the EyeLink plugin for PsychoPy with GUI components, please read the manual carefully (download manual here: Getting Started with PsychoPy / EyeLink Integration). The EyeLink plugin can be installed through the Plugin & Packages tool (see for more information: About PsychoPy Plugins — PsychoPy Plugins v0.0.1). 

It is important to note that there are two SR research plugins available in PsychoPy, but that you should only install the psychopy-eyelink plugin. This plugin was created by SR research and provides access to the EyeLink eye tracking components in PsychoPy. When using the Plugin & Packages tool, the plugin is installed per user in C:\Users\%USERNAME%\AppData\Roaming\psychopy3\packages\Python38\site-packages.

When the psychopy-eyetracker-sr-research plugin is installed, the other, non-EyeLink eye tracking components can be used (see here for more information: GitHub - psychopy/psychopy-eyetracker-sr-research: Add support to PsychoPy for SR Reseearch eyetrackers). However, these components do not have all functionalities necessary for proper eye tracker communication, such as sending messages, and thus the installation of this plugin is not advised. Moreover, installing both the psychopy-eyelink plugin and the psychopy-eyetracker-sr-research plugin may result in errors.

It is also important to note that there is an eye tracker menu in PsychoPy, that can be reached by clicking on the Experiment Setting icon (cog wheel) and going to the Eyetracking tab. An Eyetracker Device can be selected. When using the psychopy-eyelink plugin, no Eyetracker Device will become available here, and the Eyetracker Device should be set to None. When using the psychopy-eyetracker-sr-research plugin (which is not recommended), SR Research Ltd can be selected at Eyetracker Device. 

Online

Psychopy offers the option to auto-translate your python code into JavaScript (or manually add JS), so that the experiment can be run online in combination with Pavlovia. However, you should be aware that not all features are available online, and that bugs still frequently occur. For a running overview of these issues, please consult the developer crib sheet and the forum.

Tips & Tricks

Syncing to Pavlovia from network drives.

Psychopy has the functionality to upload and sync (JavaScript compatible) experiments directly to Pavlovia.org.

Testing shows that this functionality works properly if the project files are located on the local C-drive. However, in some cases it does not work if the if the experiment folder/files are located on the network drive (e.g. in the P-drive). Throwing the following error:

By default, any project located on the P-drive will show the \\VUW\.. path when initially creating the project on Pavlovia from Builder:

There are two workarounds.

1. Change this default path when first syncing to the shorter P:\  or J:\  notation, e.g.:

   \\VUW\Personal$\Homes\O\olferskjf\My Documents\Packaging\Psychopy\Experiments\BART
   
   to
   
   P:\My Documents\Packaging\Psychopy\Experiments\BART
   
   You can do this manually, or by clicking on the "Browse" button and navigating to the desired location.

2. If the above does not fix the problem, move your experiment folder to the local (C) drive, and open it from there and then sync to Pavlovia.

FAQ

Topic	Question	Answer
Error when syncing to Pavlovia	when creating a new project on pavlovia from the builder (or syncing to it), an error is thrown ending with "stderr: 'fatal: remote origin already exists".	The workaround is placing your files on the local drive (instead of P or J-drive) or adjusting the default path. See here for further details.
Blank screen when running study in local browser	Running a JS study in the local browser, using the button in the builder, only shows an empty screen in the  browser.	Make sure adblockers (like Ublock origin) are disabled or set to ignore http://localhost:12002/
2022.2.2 not syncing to Pavlovia	After installing the 2022.2.2 version, my experiments no longer sync properly to Pavlovia.	In Experiment settings, make sure "Use PsychoPy version" is set to 2022 or 2022.2.2
Any error trying to run a a task with eye tracking		In general, it may be helpful to first start PsychoPy (make sure it is the correct version, see Software list - XWiki), and then open your eye tracking task through File > Open.
	I am trying to run a task with eye tracking, but get an error: AttributeError: 'NoneType' object has no attribute 'isRecordingEnabled'	This error generally occurs when the eye tracker plugin is not installed correctly or when you are using a version of PsychoPy that does not function well with eye tracking. For Tobii, this error has been observed in version 2024.1.5 of PsychoPy. It seems that this version does not work well with Tobii. It is advised to use a different version (contact labbsuport@fsw.leidenuniv.nl).  For EyeLink, this error has been observed when trying to run a task that was created with the psychopy-eyelink plugin, but the psychopy-eyetracker-sr-research plugin is also installed and the SR research eye tracker is selected in the Eyetracking properties. A possible solution would be to remove the psychopy-eyetracker-sr-research plugin, restart PsychoPy and make sure the Eyetracker device is set to "None". To remove the plugin, remove the folders that start with psychopy_eyetracker_sr_research in C:\Users\%USERNAME%\AppData\Roaming\ psychopy3\packages\Python38\site-packages.
	I am trying to run a task with EyeLink eye tracking, but receive an error: KeyError: 'SR Research Ltd'	This error can also occur when you are trying to run a task that was created with the psychopy-eyelink plugin, but the psychopy-eyetracker-sr-research plugin is also installed and the SR research eye tracker is selected in the Eyetracking properties. See possible solution above.
	I am trying to run a task with EyeLink eye tracking, but receive an error: NameError: name 'Initialize' is not defined.	The task crashes on the Initialize component, which is usually the first EyeLink component in the task. At the start of the task, PsychoPy should ask the user to fill in the name of the EDF file (which is the EyeLink data file). When this does not happen, this type of error usually occurs.  It seems that communication with the eye tracker is not established through the plugin. The plugin is not installed, or not recognized/interpreted correctly. Make sure the plugin is installed correctly (in C:\Users\%USERNAME%\AppData\Roaming\ psychopy3\packages\Python38\site-packages).
AttributeError: 'NoneType' object has no attribute 'getIOHubDeviceClass'	I am trying to run a task with Tobii eye tracking, but receive an error: AttributeError: 'NoneType' object has no attribute 'getIOHubDeviceClass'	This error has been observed in version 2024.1.5 of PsychoPy. It seems that this version does not work well with Tobii. It is advised to use a different version (contact labbsuport@fsw.leidenuniv.nl).
PsychoPy does not start.	When starting PsychoPy, the splash screen appears but then goes away and nothing happens.	See Troubleshooting — PsychoPy v2025.2.3, deleting the preferences and app data files (userPrefs.cfg and appData.cfg) should fix the issue.

Resources

• PsychoPy website
• PsychoPy documentation: Documentation — PsychoPy v2025.1.0