Table Of Contents

Next topic

PyPsyExp Documentation

This Page

What is PyPsyExp?

PyPsyExp is a user-friendly and cross-platform library for developing psychology experiments using Python, Pygame and NumPy. While (currently) not as full featured as something like VisionEgg or the Psychophysics toolbox, our objective is to provide a clean and simple toolkit that may be exactly what you are looking for if you need a straightforward way to design a higher-level cognition experiment.

What does “higher-level” mean? It means you need a way to design simple interactive experiments that involve presenting information on a computer screen (but don’t need millisecond accuracy on display refreshes) and measuring a participant’s responses and reaction time.


  • Several input methods, such as mouse buttons and text boxes.
  • Automatic counterbalancing and data recording, across computers and even labs via FTP.
  • Complete cross-platform support; the same code should run on Windows, Macs, and UNIX machines.
  • Entirely free and open source. Free to extend in any way you want.

Quick setup


To use pypsyexp. you’ll need
  • Python 2.x: A powerful scripting language summarized here
  • NumPy: A package for numerical computation in Python.
  • PyGame: A Python wrapper for libsdl, an open source multimedia library. It has its own dependencies. Instructions for getting it working on a Macintosh can be found here.


We keep the latest versions of our code publically accessible in a subversion repository, located at

If you have never used pygame before, we recommend you begin by installing pygame along with a simple stroop task, which serves as a demonstration of how pypsyexp works:

svn co pypsyexp_demo

...which will check out the demo to the folder pypsyexp_demo.

If you are already familiar with the library and simply want to check out the latest version, this will check out the library alone:

svn co

Experiment design

The actual pypsyexp library is in the lib/ directory. In is an experiment file that loads in the library and runs an experiment that is designed to replicate the classic Stroop effect. The file follows a structure we would recommend, defining a class called StroopExperiment which extends the Experiment class defined in the pypsyexp library. To build your own experiment, you can simply alter this file to suit your needs.

For more information, check out our tutorial on the Stroop experiment here.


Documentation for the classes and functions in pygame can be found here:

Contact info

We now have an online community for discussing bugs, issues, and features of the pypsyexp system! Come join the discussion at get satisfaction.