PsychoPy is a Python-based stimulus presentation package. The PyLink library for Python, which is a fully-featured wrapper for the EyeLink C API, provides full support for EyeLink eye trackers in PsychoPy.
Programming in PsychoPy is accomplished either via a drag-and-drop, graphical Builder environment or via a Coder environment that allows you to view or edit the full Python code of your experiments.
Within the Builder, there are two options for interacting with EyeLink systems. First, you can use the EyeLink Plugin for PsychoPy, which provides a set of components for EyeLink integration.
Once the EyeLink Plugin is installed, the EyeLink components will appear in the Eyetracking section of the Components panel:
⚠️ Important: Please do not install the plugin called psychopy-eyetracker-sr-research. That is an older plugin that uses the built-in ioHub eye tracker extension for PsychoPy and does not provide full-featured EyeLink integration. Please make sure to install the plugin called psychopy-eyelink.
The second integration method within the Builder is to use Code components. This allows for more customized control by making direct calls to the PyLink module at specific moments in your experiment.
For those who prefer to work entirely in code, EyeLink integration within the Coder is achieved by calling the PyLink module directly from your Python script.
We provide example sets for each approach: using the EyeLink Plugin, using Builder with Code components, and using the Coder directly. Please see the links below.
A key advantage of PsychoPy is that any Builder experiment can be "compiled" into editable code for the Coder. This flexibility allows you to mix and match integration methods. For example, you can handle the main setup using the graphical EyeLink Plugin components, then add custom features with PyLink calls from a Code component or by modifying the compiled code directly.
Installation instructions
Templates / Example Experiments
See the installations instructions above (notably, step 4) to access the example sets for PsychoPy integration with EyeLink systems. You can also find these examples at the link below:
EyeLinkPsychoPyExamplesDocs.zip (Size: 11.07 MB / Downloads: 9)
These examples are grouped into three sets, found in the following subfolders:
1) Coder -- Shows how to use EyeLink code directly in Coder-built experiments.
2) Builder_CodeComponent -- Shows how to use EyeLink code in Code components in PsychoPy’s Builder (this is a legacy set that was developed before plugins were a feature of PsychoPy).
3) Builder_EyeLinkPlugin -- Shows how to use the EyeLink Plugin’s components to add EyeLink integration to Builder experiments, which simplifies things compared to the code-based methods.
Description of Examples
A detailed walkthrough for Coder integration, using the picture.py script as a starting point, is available in Section 5 of the Getting Started with Python and PyLink guide. The table below describes all the Coder examples provided with the EyeLink Developers Kit.
Archived example sets for legacy versions of PsychoPy Builder
Older versions of the PsychoPy Builder, which were/are not compatible with the EyeLink Plugin, have example sets that were a bit different due to some changes that PsychoPy introduced over the years. PsychoPy 2023.2.0 introduced changes affecting the way the Builder creates .py files. Then, PsychoPy 2024.1.0 introduced changes to how PsychoPy handles user dialogs (like the EDF file dialog). As a result, there are separate example sets for different, older versions of PsychoPy. If you are using one of these old versions (pre-2024), then you can find code-component based Builder examples at the links below
EyeLink Data Viewer Messaging Commands and Syntax
Throughout your experiment, in addition to sending messages to the EyeLink data file (EDF) to log event timing, it's a best practice to send special messages that allow for integration with EyeLink Data Viewer. If you use the EyeLink Plugin for PsychoPy, this is handled automatically. Alternatively, the Builder (Code Component method) and Coder examples included in the EyeLink Developers Kit illustrate how to manually send messages that convey important trial information, such as start/end times, variable values, and stimulus details. For detailed information on the messaging protocol, you can watch the EyeLink Data Viewer Integration webinar or consult the Data Viewer User Manual (via Help -> Contents) under the section "Protocol for EyeLink Data to Viewer Integration".
Documentation / Learning Resources
To learn how to use the EyeLink Plugin for PsychoPy, please refer to the EyeLink Plugin for PsychoPy User Manual, which can be found in the "Builder_EyeLinkPlugin" folder of the example sets mentioned above.
The following video tutorial explains how to use the EyeLink Plugin's components to make EyeLink experiments from PsychoPy's Builder.
Video Tutorial: EyeLink Plugin for PsychoPy (Builder Interface)
The following video tutorial provides for the Coder interface provides an overview and a detailed walkthrough of the picture.py example/
Video Tutorial: EyeLink / PsychoPy Integration Tutorial (Via Coder Interface)
The PyLink API User Guide and the Getting Started with Python and PyLink guide contain the primary documentation; both are included with the EyeLink Developers Kit and are located in the SampleExperiments/Python/ directory.
For advanced users, the EyeLink Programmer's Guide provides complete documentation of the underlying C API. While the syntax differs from PyLink, the core functionality of the functions is analogous and can provide deeper insight.
Programming in PsychoPy is accomplished either via a drag-and-drop, graphical Builder environment or via a Coder environment that allows you to view or edit the full Python code of your experiments.
Within the Builder, there are two options for interacting with EyeLink systems. First, you can use the EyeLink Plugin for PsychoPy, which provides a set of components for EyeLink integration.
Once the EyeLink Plugin is installed, the EyeLink components will appear in the Eyetracking section of the Components panel:
⚠️ Important: Please do not install the plugin called psychopy-eyetracker-sr-research. That is an older plugin that uses the built-in ioHub eye tracker extension for PsychoPy and does not provide full-featured EyeLink integration. Please make sure to install the plugin called psychopy-eyelink.
The second integration method within the Builder is to use Code components. This allows for more customized control by making direct calls to the PyLink module at specific moments in your experiment.
For those who prefer to work entirely in code, EyeLink integration within the Coder is achieved by calling the PyLink module directly from your Python script.
We provide example sets for each approach: using the EyeLink Plugin, using Builder with Code components, and using the Coder directly. Please see the links below.
A key advantage of PsychoPy is that any Builder experiment can be "compiled" into editable code for the Coder. This flexibility allows you to mix and match integration methods. For example, you can handle the main setup using the graphical EyeLink Plugin components, then add custom features with PyLink calls from a Code component or by modifying the compiled code directly.
Installation instructions
- Configure your Display PC's network connection to communicate with the EyeLink Host PC.
- Download and install the latest version of PsychoPy.
- From there, the easiest way to install everything you will need to interface with EyeLink systems via the Builder or the Coder is to install the EyeLink Plugin -- doing so will install all the packages that PsychoPy needs (PyLink, the EyeLink Plugin's GUI components, and the EyeLink core graphics for PsychoPy (which handles EyeLink camera setup/calibration/validation/drift check functionality).
- Option A (Recommended): Install using PsychoPy's Plugin/packages manager
Launch PsychoPy and go to “Tools -> Plugin/packages manager…”. Find the SR Research Eyetracker Support plugin called psychopy-eyelink and click the Install button. Note, make sure not to install the plugin called psychopy-eyelink-sr-research, as that is only a partial wrapper of Pylink that does not include many critical aspects of EyeLink functionality. Instead, install the one called psychopy-eyelink, which provides fully-featured integration with EyeLink systems.
- Option B (Alternative): You can alternatively install all the packages needed using PIP commands. An easy way to get to a PIP terminal in PsychoPy is via the Plugin/packages manager. In the Packages tab, click the Open PIP terminal button. From the PIP terminal, type the following command:
install psychopy-eyelink --upgrade --user
Note, for versions of PsychoPy earlier than 2025.1.1, the command must include "pip" at the beginning, but for versions starting 2025.1.1 the pip should be omitted:
Code:install sr-research-pylink --user --upgrade
- Option A (Recommended): Install using PsychoPy's Plugin/packages manager
- Deploy the examples and documentation to your computer's Documents folder. You can do so by launching Coder (Window -> Show Coder), pressing Enter to start a Python shell, and then typing the following two commands into the Python shell (note, these commands use underscores between the text “psychopy” and “eyelink” and between “deploy” and “examples”):
Code:>>> import psychopy_eyelink
>>> psychopy_eyelink.deploy_examples()
These commands will place a copy of the example sets in your operating system’s Documents folder, in a folder called EyeLinkPsychoPyExamplesDocs. If an existing folder with the same name is detected, the folder that is already in the Documents folder will be renamed with the date/time appended to the folder name before the fresh set of examples is placed there (in case you have saved your own experiments or other materials there).
- Restart PsychoPy -- you must restart PsychoPy for it to load/update the packages that have been installed.
- Optional -- you may also install the EyeLink Developers Kit / API, which includes accessory applications and resources that are useful for EyeLink systems more generally.
Templates / Example Experiments
See the installations instructions above (notably, step 4) to access the example sets for PsychoPy integration with EyeLink systems. You can also find these examples at the link below:
EyeLinkPsychoPyExamplesDocs.zip (Size: 11.07 MB / Downloads: 9)
These examples are grouped into three sets, found in the following subfolders:
1) Coder -- Shows how to use EyeLink code directly in Coder-built experiments.
2) Builder_CodeComponent -- Shows how to use EyeLink code in Code components in PsychoPy’s Builder (this is a legacy set that was developed before plugins were a feature of PsychoPy).
3) Builder_EyeLinkPlugin -- Shows how to use the EyeLink Plugin’s components to add EyeLink integration to Builder experiments, which simplifies things compared to the code-based methods.
Description of Examples
A detailed walkthrough for Coder integration, using the picture.py script as a starting point, is available in Section 5 of the Getting Started with Python and PyLink guide. The table below describes all the Coder examples provided with the EyeLink Developers Kit.
| Template | Description |
|---|---|
| picture | This is a basic example, which shows how to connect to and disconnect from the tracker, how to open and close data files, how to start / stop recording, and the standard messages for integration with the Data Viewer software. We show four pictures one-by-one on each trial, and a trial terminates upon a keypress response or until 3 secs have elapsed. |
| pursuit | This example script shows how to record the target position in a smooth pursuit task. This script also shows how to record dynamic interest area and target position information to the EDF data file so Data Viewer can recreate the interest area and playback the target movement. |
| saccade | This example script shows how to retrieve eye events (saccades) during testing. A visual target appears on the left side, or right side of the screen and the participant is required to quickly shift gaze to look at the target (pro-saccade) or a mirror location on the opposite side of the central fixation (anti-saccade). |
| fixationWindow_fastSamples | This is a basic example, which shows how to implement a gaze-based trigger. First a fixation cross is shown at the center of the screen. The trial moves on only when gaze has been directed to the fixation cross. |
| GC_window | This script shows how to manipulate visual stimuli based on real-time gaze data. A mask is shown at the current gaze position in the "mask" condition; in the "window" condition, the image is masked, and a window at the current gaze position will reveal the image hidden behind the mask. |
| MRI_demo | This is a basic example illustrating how to do continuous eye tracker recording through a block of trials (e.g., in an MRI setup), and how to synchronize the presentation of trials with a sync signal from the MRI. With a long recording, we start and stop recording at the beginning and end of a testing session (run), rather than at the beginning and end of each experimental trial. We still send the TRIALID and TRIAL_RESULT messages to the tracker, and Data Viewer will still be able to segment the long recording into small segments (trials). |
| video | A simple video demo. In each trial eye movements are recorded while a video stimulus is presented on the screen. Integration messages allow the video to play back in Data Viewer |
Archived example sets for legacy versions of PsychoPy Builder
Older versions of the PsychoPy Builder, which were/are not compatible with the EyeLink Plugin, have example sets that were a bit different due to some changes that PsychoPy introduced over the years. PsychoPy 2023.2.0 introduced changes affecting the way the Builder creates .py files. Then, PsychoPy 2024.1.0 introduced changes to how PsychoPy handles user dialogs (like the EDF file dialog). As a result, there are separate example sets for different, older versions of PsychoPy. If you are using one of these old versions (pre-2024), then you can find code-component based Builder examples at the links below
- Archived/Legacy Example Sets for older versions of the PsychoPy Builder:
PsychoPy_Builder_Examples_For_Versions_2023.1.3_And_Earlier.zip (Size: 3.88 MB / Downloads: 166)
PsychoPy_Builder_Examples_For_Versions_2023.2.x.zip (Size: 3.77 MB / Downloads: 63)
EyeLink Data Viewer Messaging Commands and Syntax
Throughout your experiment, in addition to sending messages to the EyeLink data file (EDF) to log event timing, it's a best practice to send special messages that allow for integration with EyeLink Data Viewer. If you use the EyeLink Plugin for PsychoPy, this is handled automatically. Alternatively, the Builder (Code Component method) and Coder examples included in the EyeLink Developers Kit illustrate how to manually send messages that convey important trial information, such as start/end times, variable values, and stimulus details. For detailed information on the messaging protocol, you can watch the EyeLink Data Viewer Integration webinar or consult the Data Viewer User Manual (via Help -> Contents) under the section "Protocol for EyeLink Data to Viewer Integration".
Documentation / Learning Resources
To learn how to use the EyeLink Plugin for PsychoPy, please refer to the EyeLink Plugin for PsychoPy User Manual, which can be found in the "Builder_EyeLinkPlugin" folder of the example sets mentioned above.
The following video tutorial explains how to use the EyeLink Plugin's components to make EyeLink experiments from PsychoPy's Builder.
Video Tutorial: EyeLink Plugin for PsychoPy (Builder Interface)
The following video tutorial provides for the Coder interface provides an overview and a detailed walkthrough of the picture.py example/
Video Tutorial: EyeLink / PsychoPy Integration Tutorial (Via Coder Interface)
The PyLink API User Guide and the Getting Started with Python and PyLink guide contain the primary documentation; both are included with the EyeLink Developers Kit and are located in the SampleExperiments/Python/ directory.
- Windows: C:/Program Files(x86)/SR Research/EyeLink/SampleExperiments/Python/
- Mac: /Applications/Eyelink/SampleExperiments/Python/
- Linux: /usr/share/EyeLink/SampleExperiments/Python/
For advanced users, the EyeLink Programmer's Guide provides complete documentation of the underlying C API. While the syntax differs from PyLink, the core functionality of the functions is analogous and can provide deeper insight.