| Reference | Downloads | Github

Best practices for using multiple PsychoPy versions on one computer


I’m currently designing PsychoPy experiments that will be used at an MRI-scanner facility. Some of the experiments will be done with the participant inside of the MR camera, others outside of it. In both cases we need to run PsychoPy on computers used by different research groups.

When we asked about using PsychoPy at the facility the staff sighed, because they’ve had issues with running different versions of PsychoPy on the computers. Some research groups have experiments that are >5 years old while others (including us) want to use one of the latest versions. They’ve tried using anaconda but they still have problems now and then. It’s a problem for us if we can’t rely on PsychoPy working as expected when we get there, and to me it’s also a shame that the staff’s view of PsychoPy (which I mostly quite like) is darkened by this.

So, I’m trying to figure out the best way to tackle this challenge of running PsychoPy experiments built using vastly different versions. I’m thinking that if I can figure this out, it would help the project I work for, and I could share the info with the MRI staff as well and hopefully brighten their opinion on Python.

Looking through the forums I’ve found similar earlier threads, with different proposed solutions, e. g.:

  • - Install complete standalone Psychopy versions, making sure to rename the older version before adding another
  • (mentions that separate standalone installations aren't possible - maybe this changed in the time between this and the previous thread?) - use:
    import psychopy

    (it’s mentioned however that “that doesn’t really work for Builder though”)

  • - use the useVersion function to control which version of PsychoPy is used to run the task. This can be set from Experiment Settings > Use Version.

    I wasn’t able to find any documentation about the psychopy.useVersion() command in the manual unfortunately. The closest I found was this post in Google Groups from 2014.

    My workflow is that I put together experiments in the Builder, let it generate a .py script, and then add some tweaks in the Coder View for specific functionality that’s needed. The end product is a .py file, with accompanying stimuli and a .csv file for loop variable values.

    If I’ve understood things correctly I can’t really run my .py files directly from the command line, since PsychoPy requires a specific environment, meaning the script has to be opened and run using the PsychoPy app/program. (so I use open -a /Applications/ in the Terminal) This stops me from just using pipenv to create a virtual environment for version control (please correct me if I’m wrong).

    Now, if one has installed the standalone version 3.2.4 of PsychoPy, can one simply add the import statement and python.useVersion(’<version_no>’) to the beginning of the .py script in the Coder view? And then everything will work out fine as long as the correct version is specified, no matter how old that version is? Also, does one have to have git installed, as this thread seems to suggest?

    And if people prefer, can they simply open up their .psyexp file, go to Experiment Settings in the Builder View, then choose the version they need? Looking at this setting on my computer, I see versions spanning from 1.90.0 to 3.2.4 - is a separate standalone installation required if someone needs to use versions earlier than 1.90.0?

    If anyone can help me out on this I would be very grateful :smiley_cat: Versioning in my limited experience seems to almost always be a headache in Python, and so everything I can get right from the get-go is a godsend.

1 Like

That is no longer true - as you note, this setting is now available via Builder. It is saved with the experiment file, so the user doesn’t need to switch versions themselves, they just run the experiment like any other. The first time it runs on a given computer, however, there might be a pause while the relevant previous version code is downloaded in the background.

This is generally not a good workflow: it is far preferable to use code components within the Builder interface. They will automatically insert your custom code to run at the correct time in the script (e.g. at the beginning of the experiment, the the beginning of the routine, on every screen refresh, etc), while still allowing you to keep making tweaks to components via the graphical interface. There are very few occasions now when it might be necessary to edit the generated .py. file manually.

A specific advantage to staying within the Builder interface here is that you get to see the specific list of supported previous versions available to useVersion() because only the relevant versions are shown in the popup menu. If you are tweaking the code manually, you just have to guess.

It uses git to download the code from the PsychoPy Github repository needed to run the experiment under a given previous version.

The standalone version has this bundled for you already. If you are installing PsychoPy as a library (e.g. inside an Anaconda environment, then yes, git would be needed too.)

I think the list of available previous versions will differ depending on whether the standalone version you are running is Python 2 or 3 and 23 or 64 bit. So to get earlier versions, you might need, say, a Python 2, 32 bit standalone (I’m not sure - test it out).

We hope that this feature means that psychoPy handles most of the headache for you, but there are some limitations. As Python 2 gently retires, and people converge on 64 bit installations, then into the future, you should have more confidence that the list of previous versions available should continue to grow.

1 Like

Thank you very much! This helps a lot.

Great, thanks. Something I didn’t think of before though, does this mean that for running versions earlier than the one installed, one has to be connected to the internet? Granted, there is internet access almost everywhere now, but sometimes (e. g. at the MRI facility I mentioned) there might be issues with the internet connection. A colleague described how it was very frustrating with how Matlab, which she used in the past, wouldn’t run without an internet connection, and she hoped PsychoPy would make that a non-issue. Would it be possible to make a local clone of the git repo and reroute the useVersion() requests to that clone, to avoid having to rely on an internet connection? (if this is too complicated to answer that’s fine)

My understanding of the code snippets component is that you can add on things to be run at “Begin Experiment”, “Begin Routine”, “Each Frame”, “End Routine”, “End Experiment”, but not really edit the generated code itself. Maybe it’s a lack of creativity on my part, but I often find myself in situations where what I want to do doesn’t fit into that format. Actually, looking now at changes I’ve done, some of them can be solved using code snippets and so I should do that, but not all I think. I’ll use the most recent project I worked on to illustrate:

  • I want the ‘correct answer’ for a keyboard component to change for each trial, based on whether two sound stimulus that are used (specified using a variable fetched from .csv) are the same or not. There isn’t an option to set the ‘correct answer’ option for the keyboard component to ‘repeat every frame’. So I manually changed the relevant code to:
                if rhythm_first == rhythm_second: # check if 1st n 2nd rhythm .wav are the same
                    correct_resp = 'right'
                    correct_resp = 'left'
                # was this 'correct'?
                if rhythm_key_same_or_diff.keys == correct_resp:
                    rhythm_key_same_or_diff.corr = 1
                    rhythm_key_same_or_diff.corr = 0

Things like this pop up every now and then.
Edit: Ohhhh, you CAN use $variable names in components that can’t be set to ‘repeat every frame’. I don’t know where I got this idea, I’ve been making my life much harder. So disregard this stuff.

Praised be the day :wink:

Not for running in general, but an internet connection is needed for the first time an experiment is run with a previous version specified. On that first run, the needed files are downloaded and installed. They will be locally available on subsequent runs, so no connection is needed thereafter.

That is beyond me, sorry, but probably nothing that complicated is needed. If the solution above isn’t feasible (having a one-off internet connection), then you could probably just set up PsychoPy on another computer that can be connected to the net, and then copy that installation over.

Perhaps a key thing to realise is that the positioning of the code component is important in terms of when the code runs. i.e. if you are setting a variable that a stimulus component needs to refer to, then ensure the relevant code component is placed above the stimulus component, so that the latter gets to refer to the current version of that variable (whether per trial or per frame). Conversely, if you want to take action in response to a keypress, ensure the code component is placed below the keyboard component, so it gets access to the latest response, rather than lagging it by a screen refresh.

1 Like

Brilliant, I didn’t expect things to be that simple. It seems like you’ve worked out a really good system for how to deal with these things, it’s just not really documented? Unless I completely missed it even though I tried to look around. Hopefully others will search the forums and find your answers here :slight_smile:

Nope, the go-to solution you described should totally work.

Again, thank you!

The PsychoPy project is a community effort. We are always looking for users who would be prepared to make edits and additions to improve the documentation, which is hosted on Github:

It is a great way to give back to the project, if you can spare the time.

1 Like

I had a shot at contributing a text, but it wasn’t very clear to me how I should go about it. In the github repo I found this document about contributing. It says " For simple changes, and for users that aren’t so confident with things like version control systems then just send your changes to the PsychoPy forum.". Should I start a new thread, or send it to a particular user? As someone totally new to this, starting a new thread for a small doc fix seems a bit excessive/intimidating, so it might make people refrain from contributing. I also didn’t know in what format I should describe the suggested changes - in a .txt file, or a .rst file, or just write everything in a forum post? I haven’t written in the restructured text format before, so that was new to me. And I also didn’t really know what style/tone I should use in the text, or what part of the site that information about version handling should belong to.

Anyway, I thought I’d essentially boil down your tips into a guide and format it according to .rds. But now that I try to upload the file here, I’m informed that:
“Sorry, the file you are trying to upload is not authorized (authorized extensions: jpg, jpeg, png, gif, ico, icns, py, psyexp, csv, xlsx, wav).”
So I guess I’ll link to a github repo where I’ve uploaded the file:

I thought that maybe the text would fit into the site’s FAQ section, but I really don’t know. I hope the text can be of some use, please modify it as necessary. Also I don’t mean to whine about the contribution process, I just figured it might be helpful to hear about the challenges for a newcomer.


Thanks for making the effort, we appreciate it. There is value in someone contributing content to the documentation who has actually run up against issues, because you are in a position to see what is missing from the perspective of a person who actually needed to learn the information.

Unfortunately the link above doesn’t resolve. Perhaps just try pasting in the raw text here?

Sorry, I had the repo set to private by accident. You ought to be able to reach the file now. In case there would be any problem, here’s the original text (the text is chopped up since I use <pre> tags to preserve the formatting information, so just copy-paste the whole block into a text editor to see the whole thing)

.. _versioning:

Using different PsychoPy versions

If you perform experiments on computers shared by different research groups (e. g. at a shared experimental facility), it's possible that their experiments and yours are written using different versions of PsychoPy. Or maybe you yourself have some older and some newer experiments. In such a situation, it's important to ensure that the right version of PsychoPy is used for the right experiment.

In `PsychoPy standalone `_, there is an easy-to-use system for controlling what version of PsychoPy is used. 

Version control using Builder View
1. Open up the PsychoPy experiment file (a '.psyexp' file) that contains the experiment you want to use. 
2. Go to experiment settings by clicking the icon with a cogwheel. 
3. Under the "Basic" settings tab, there is an option named "Use PsychoPy version". Set it to the PsychoPy version you want to emulate. 
4. Click "OK" to save the settings. 
5. Run the experiment by clicking the green 'run' button.

Version control using Coder View
1. Open up the PsychoPy script file (a '.py' file) that contains the experiment you want to use. 
2. Add :code:`import psychopy` at the top of your script, where the other import statements are.
3. Add the function call :code:`psychopy.useVersion('')` (e. g. :code:`psychopy.useVersion('1.90.2')`) directly below your import statements.
4. Run the script.

NOTE: Internet connection needed (the first time)
You need to have a working internet connection the first time that you run an experiment using a particular version (e. g. 1.90.2) on a computer, so that PsychoPy can download some info about the version for you. Once you've used a version once, your computer has saved the information it needs for emulating it. This means that after the first time, you don't need an internet connection if you run the same or another experiment using that version (e. g. 1.90.2).

Using either of the above methods, you should often only need the latest version of PsychoPy standalone to run older experiments. However, if you have an experiment designed with a very old version of PsychoPy (say, version 1.77.01) you might have to install an older version of standalone PsychoPy. Since these things change over time, you probably want to search for help in the `PsychoPy forums `_. 

Yes, that works, and this is great content.

If you want to incorporate this yourself into the PsychoPy repository, you could hit the green button at to clone the repo to your own fork at

Then download that fork to your own computer, where you can work on the files. Make a new branch with git checkout -b versiondocs Add your .rst file in the psychopy/docs/source/ directory, and make links to it from relevant other .rst pages so that you can set where it will appear.

If you go to you local local Python installation and

pip install sphinx hieroglyph

Then from the Terminal in the psychopy/docs/ folder, you simply type:


then the HTML and PDF help documents will be generated for you locally to check. If happy, you can git add just the changed .rst files, git commit them, and then git push origin versiondocs to send that branch and commits to your fork on Github. From there (i.e. on Github), issue a pull request to the main PsychoPy repo, with the subject starting with "DOCS: "

That way, you will get the credit as a PsychoPy developer, and will be set up for future contributions. If that seems like too much work, let me know, and I’ll add it myself.

Thanks for the instructions, I did my best and there should be a pull request waiting now.

It took me a little digging to figure out how linking between .rst files works. Since the FAQ seemed like the most appropriate spot I put the .rst in the faq folde there, after understanding that the index file ensures that all the .rst files in that folder will be linked to.

Just running <make on it’s own didn’t work, it presented me with different command options. I used “make html”. It ran, but while producing an incredible amount of error messages. It seemed like some of the things that started happening were meant for running on a Windows setup, not a Mac? The HTML files it produced looked okay though. (some of the error messages might be due to issues specific for my computer, since I suspect I’ve messed up python installations in the past)

:+1: Well done, thanks for contributing and making this easier to understand for other users.