Installation headaches and (partly) fixes on Ubuntu 20.04

Important! @jon wrote a reply further down and suggested what is probably a much easier solution. (not marked as solution yet since there’s only one who has confirmed that it works for them)

I started this to ask for help, but then I found out more myself, so now I’m mostly putting this here to help anyone else who might try to install PsychoPy on Ubuntu in the future.

Missing gcc/python-3-dev packages

I’m using a fresh install of Ubuntu 20.04, with python v. 3.8.2. I tried to follow the installation instructions for Linux-based systems, which end with:

pip install psychtoolbox

So I set up a virtual environment with venv, ran the previous commands (pip install psychopy installing the appropriate wxPython wheel and building psychtoolbox bindings), then executed the above command from inside it. But then I got errors, saying among other things

unable to execute ‘x86_64-linux-gnu-gcc’: No such file or directory
C compiler or Python headers are not installed on this system. Try to run:
sudo apt-get install gcc python3-dev

I followed the instructions and ran sudo apt-get install gcc python3-dev (from outside of the virtual environment). I then tried pip install psychtoolbox (from inside the venv) again, and this time it seemed to work.

Missing Simple Directmedia Layer (SDL) libraries

However, when I tried to start psychopy (psychopy from within venv), I got “ImportError: cannot open shared object file: No such file or directory”. Some duckduckgo:ing lead me to try sudo apt-get install libsdl2-2.0 (outside of the venv). Now finally when I ran psychopy (within venv), PsychoPy3 Builder started up.

Missing Qt platform plugin

I created a “hello world” experiment and tried to run it. I however got another error message, ‘Could not load the Qt platform plugin “xcb” in “” even though it was found…’. I looked around, found this thread, ran sudo apt-get install libxcb-xinerama0 (outside venv), which fixed this issue.

PsychToolBox (PTB) priority error

(EDIT: If you’re fine without PTB and using PsychoPy’s fallbacks - which I don’t know much about - look at @Catherine_Hanson’s replies further down in this thread, which seem to describe a simpler solution, based on a post by @Michael)

(EDIT2: There is another thread which discusses a PTB-CRITICAL error which looks to be the same as the one I describe here, and there is a clarification of a solution from @aforren1 there that reportedly has worked.)

When running PsychoPy experiments again now, I got “PTB-CRITICAL: In call to PsychSetThreadPriority(): Failed to set new basePriority 2, tweakPriority 1, effective 1 [REALTIME] for thread (nil) provided!”. I searched around a bit and found this fairly obscure solution described by the user Detlef:

(before using this, you might want to read on and see if you can skip the very hefty downloads here)

sudo apt install octave
sudo apt install psychtoolbox-3-common
sudo apt install octave-psychtoolbox

Then cding into ‘/usr/share/psychtoolbox-3/’, running sudo octave --no-gui, then (in the Octave shell) PsychLinuxConfiguration.m, and answering yes to seemingly relevant questions, above all the ones related to creating a new user group with special privileges (making sure to add not only root, but my own user account to it as well).

I had a look at the “PsychLinuxConfiguration.m” file. It looks like the commands related to user privileges that it actually executes are:

sudo groupadd --force psychtoolbox
sudo usermod -a -G psychtoolbox <username>
sudo usermod -a -G dialout <username>
sudo usermod -a -G lp <username>
sudo usermod -a -G video <username>

(replace with your own Ubuntu username, of course)
The script also creates a new file (on my system, and presumably all Ubuntu systems) in the directory “/etc/security/limits.d/”, at least in my case this file was “/etc/security/limits.d/99-psychtoolboxlimits.conf”. The contents are simple, with the relevant lines being:

@psychtoolbox   -  nice       -20
@psychtoolbox   -  rtprio     50
@psychtoolbox   -  memlock    unlimited

(if /etc/security/limits.d/ doesn’t exist, the matlab script modifies a configuration file at /etc/security/limits.conf, but again, I’m guessing all Ubuntu installations come with the “limits.d” folder)
I think those are the only things that are really needed for dealing with the “Priority()” issue.

Remaining glitches

In spite of all the above steps, things still don’t work entirely as they should.

Note how the Psychopy icon in the desktop sidebar to the left (fifth icon from the top) is very glitchy and doesn’t look at all the way it should - it’s the same thing if I e. g. alt+tab over to PsychoPy - the icon is broken. The components in PsychoPy’s right sidebar don’t have any images to represent them, instead it’s all text.

In sum

Those are a lot of hoops that I had to jump through to make PsychoPy run on a clean Ubuntu installation, and even now it’s glitchy. I had to install a bunch of packages that take up a lot of space, and I’m not sure if I can just uninstall them now without breaking PsychoPy. I’d say that at the moment, at least the most recent versions (I used ‘2020.2.4post1’, as this is what was automatically installed by pip) of PsychoPy don’t seem to really be compatible with Ubuntu. There are also a number of threads filled with frustration about this, e. g. this one or this one.

As noted in the latter thread I linked above, it’s hard to make sure that instructions include all necessary dependencies et c. for all Linux users, and there are limited resources for open source projects. But perhaps the installation instructions could be changed so that they explicitly explain that A) many users have trouble setting up PsychoPy on Linux platforms, and B) it’s strongly recommended that users if possible instead use a Windows/Mac computer with the standalone version, and otherwise they are more or less on their own. This could save a lot of time for everyone involved, I think.


Hi there,

I just wanted to thank you for your thorough documentation of this problem and the steps that you have taken. This will be useful both for the developers and users as we move forward thinking about cross platform installation. Sorry that you had a difficult time installing, but thank you for sharing the approaches and solutions you found along the way.


I, too, would like to thank you deeply for your explanation and description. Your problems are exactly the ones I ran into and I agree that more linux support would be very much appreciated. Your suggestions were extremely helpful. I love PsychoPy once it’s working, but getting it installed has become harder and harder over the years.

1 Like

Re the psychtoolbox problem I did uninstall it as suggested here and now my simple builder text script ran.

1 Like

AND the demos now work!

After installing PsychoPy from scratch I also had the PTB priority error on openSUSE Leap 15.2. As far as I understand from the error message, Psychopy is not run with the correct real-time permissions / task priority when started as a normal user. Following the above instructions, I first created the group “psychtoolbox” and added the user to this group:

sudo groupadd --force psychtoolbox
sudo usermod -a -G psychtoolbox <username>

Then I added a new file called “99-psychtoolboxlimits.conf” in the directory “/etc/security/limits.d/” (which was empty). The content of the file was as above:

@psychtoolbox   -  nice       -20
@psychtoolbox   -  rtprio     50
@psychtoolbox   -  memlock    unlimited

After a reboot PsychoPy worked nicely, maybe this helps for cross platform installations.


Dear Arboc,

Thank you very much for this thorough and in-depth explanation. This is THE definitive guide on how to make psychopy3 work on Ubuntu 20.04 (fully updated version). I would vote to put this onto the official installation instructions.

There is only 1-2 things I’d like to add:

  1. It’s probably best to first create a bare-bones conda environment with python=3.6, (since later on you might have to install pyqt). Then start doing the Linux instructions from the beginning. Skip all the stuff with the environment.yml file, it doesn’t work.
  2. you need to grab the libwebkitgtk-1.0 libraries somewhere. I googled and found:
    dependencies - How to install the libwebkitgtk package on Ubuntu 20.04 LTS? - Stack Overflow

Best wishes

1 Like

Also, you need to downgrade the psychotoolbox with pip, because newer releases of psychtoolbox breaks the detection of keyboards, and you get an oblique error in

So downgrade psychtoolbox with conda or pip to version 3.0.16.

Sorry that installing on Debian/Ubuntu hasn’t been easier. I’m afraid the core team developing PsychoPy is very small and busy!

That said, I just tried to install on a VM running a clean install of Ubuntu 20.04 and this appears to work:

sudo apt-get install psychopy   # fetches outdated version from debian
sudo apt-get install python3-pip python3-wxgtk-webview4.0 
# update to latest psychopy:
pip3 install -U psychopy  
 # fix some incompatible lib versions:
pip3 install cffi==1.14.0 psychtoolbox==3.0.16 

Those 4 lines should be enough that you can now start PsychoPy and edit experiments!

To get psychtoolbox working for keyboard use you also need the following steps to raise the priority of the experiment process:

sudo groupadd --force psychtoolbox
sudo usermod -a -G psychtoolbox $USER

then do sudo nano /etc/security/limits.d/99-psychopylimits.conf and copy/paste in the following text to that file:

@psychtoolbox   -  nice       -20
@psychtoolbox   -  rtprio     50
@psychtoolbox   -  memlock    unlimited

Thanks all those (in this and other threads) that contributed to the above lines in one way or another :slight_smile:

1 Like

Yippie, thanks a lot Jon!

This manual helped me installing Psychopy on very recent Debian Bullsyeye.

  • libwxgtk-webview3.0-gtk3-0v5:amd64 is available as deb.
  • manually had to install: pip install pyosf
  • Psychtoolbox is now version, this installs without error (3.0.16 gave error).

Only issue (but without impact so far) is a message in runner’s stdout:

RuntimeError: module compiled against API version 0xe but this version of numpy is 0xd
(I do have: version 1.19.5, from system, accepted/used by pip)

1 Like

Ran all of these commands suggested on Ubuntu 20.04.4 LTS and psychopy crashes immediately upon running it, without any error message.
I definitely recommend that the official page removes the claim that it supports linux. I deleted my windows dual-boot in order to set up ubuntu, based off of the claim that it was supported. Now I’ll have to undo all of that work.