PsychoPy Installation Script for Linux

---

This script facilitates the installation of PsychoPy on various Linux distributions, including:

• Ubuntu 24.04, 22.04, 20.04, (18.04*)
• Pop!_OS 22.04
• Debian 12, 11
• Fedora 41, 40, 39
• Rocky Linux 9
• CentOS 9
• Linux Mint 22
• OpenSuse 15
• Manjaro 25

These distributions have been tested for compatibility, but the script may also work on other Linux distributions.

Notes:

• *Ubuntu-18.04 fails to install PyQt6. You can still use Ubuntu-18 with PsychoPy versions =< 2023.2.3. Earlier versions use PyQt5.
• Arch Linux worked in my testing. I had to increase /tmp size to be bigger than 4GB, and since there are no prebuilt wxPython wheels for Arch, it has to be built from source.

Table of Contents

1. Important Information
2. Usage
3. Options
4. Example
5. Script Details
6. Post-Installation
7. Uninstalling PsychoPy
8. Troubleshooting
9. Contributing & Support

Important Information

• This script will install multiple dependencies based on your Linux distribution. A detailed list of packages that may be installed is available here (click "Uninstall dependencies by package manager" to expand).
• A directory is created at ${INSTALL_DIR}/PsychoPy-${PSYCHOPY_VERSION}-Python${PYTHON_VERSION} (--install-dir, default: /usr/local/psychopy). Use --venv-name=NAME to replace the versioned subdirectory with a custom name (${INSTALL_DIR}/${NAME}).
• The script attempts to install Python via the package manager; if not found, it downloads a pre-packaged .tar.gz from GitHub releases or, if unavailable, from python.org to build from source.
• Default(3.10)/specified Python version is installed as altinstall into /usr/local/psychopy/python if not available via package manager.
• PsychoPy supports Python versions 3.8, 3.9, and 3.10.
• wxPython is downloaded from the official site; if this fails, the script tries GitHub releases or builds from source.
• After successful wxPython installation, the downloaded .whl file is cached in /usr/local/psychopy/python/wx_wheels.
• If the downloads fail, building Python and wxPython may take some time.
• The script provides minimal output to terminal. Use the --verbose option for detailed logging (logfile output is always verbose).
• Logs are written to a timestamped file in /tmp/psychopy_linux_installer_YYYYMMDD_HHMMSS.log first and then moved into the installation folder.

Usage

Install curl with your package manager. On most distros curl is already installed.

1. Download the script:

   curl -LOs https://github.com/wieluk/psychopy_linux_installer/releases/latest/download/psychopy_linux_installer

2. Make it executable:

   chmod +x psychopy_linux_installer

3. Run the installer:

   • GUI Mode:

     ./psychopy_linux_installer --gui

     curl and zenity are required for the GUI mode.

   • Command-Line Mode:

     ./psychopy_linux_installer

Options

Option	Description	Default
--psychopy-version=VERSION	Install a specific PsychoPy release.	latest
--python-version=[3.8|3.9|3.10]	Choose the Python interpreter version used by PsychoPy.	3.10
--wxpython-version=VERSION	Install a specific wxPython release.	4.2.2
--install-dir=DIR	Target directory for the installation.	/usr/local/psychopy
--venv-name=NAME	Custom name for the virtual‑env folder (must not be python when using the default install‑dir).	(auto: versioned subfolder)
--additional-packages=PKG,PKG,…	Extra pip packages to install (package==version syntax allowed).	(none)
--requirements-file=FILE	Install all pip packages from FILE (e.g. a requirements.txt generated by the PsychoPy BIDS plugin) into the PsychoPy virtual environment.	(none)
--build=[python|wxpython|both]	Build Python and/or wxPython from source instead of downloading wheels/binaries.	(download pre‑built wheels)
--sudo-mode=[ask|auto|error|continue|force]	Control sudo usage. ask: confirm, auto: auto-confirm, error: exit if sudo needed, continue: continue without sudo, force: use sudo directly.	ask
--non-interactive	Bool. Run unattended; implicitly sets --sudo-mode=auto unless already given.	false
--disable-shortcut	Bool. Prevent creation of a desktop shortcut.	false
--disable-path	Bool. Skip linking PsychoPy to /usr/local/bin.	false
--remove-psychopy-settings	Bool. Delete existing user settings at ~/.psychopy3 while installation.	false
--gui	Bool. Open a graphical installer (command‑line options are ignored while GUI is running).	false
-f, --force-overwrite	Bool. Overwrite the target install folder—that is, the version‑specific subdirectory inside --install-dir (or the folder named by --venv-name) if it already exists.	false
-v, --verbose	Bool. Print verbose progress messages to the terminal.	false
--version	Print the installer script version and exit.	(n/a)
-h, --help	Show usage information and exit.	(n/a)

Note:

• Non-Admin Installation: The --sudo-mode=continue option enables non-admin users to upgrade or reinstall if the required Python version and packages are already installed. This option assumes an administrator has previously run the installation.
• Version Selection: The --psychopy-version and --wxpython-version options accept specific versions from PyPI, as well as latest or git. Note that git versions may be unstable and are generally not recommended.

Example

./psychopy_linux_installer --psychopy-version=2024.2.4 --python-version=3.10 --install-dir=/home/ubuntu --venv-name=custom-psychopy --additional-packages=psychopy_bids,seedir,psychopy-crs==0.0.2 --sudo-mode=auto --build=python --verbose --force-overwrite

Script Details

The script performs the following steps:

• Detects the package manager (supports apt, yum, dnf, pacman, and zypper).
• Installs all necessary dependencies.
• Sets up the PsychoPy installation directory.
• Installs the specified Python version as altinstall if needed.
• Creates a virtual environment and installs/builds wxPython.
• Upgrades pip and required pip packages.
• Installs the specified PsychoPy version.
• Adds the current user to a psychopy group and sets security limits.
• Generates a startup wrapper script (start_psychopy) in the installation directory.
• Adds a symbolic link to the PsychoPy startup wrapper in /usr/local/bin/.
• Adds a desktop shortcut.

Post-Installation

After installation, desktop icons for PsychoPy will be created automatically, and the application will be added to your system's PATH as:

PsychoPy-${PSYCHOPY_VERSION}-Python${PYTHON_VERSION} or ${VENV_NAME}

You can also launch PsychoPy directly using the absolute path:

${PSYCHOPY_DIR}/start_psychopy

Please reboot to apply security limits.

Note: All commands, along with the installed versions and set paths, will be displayed at the end of the script.

Uninstalling PsychoPy

To completely remove PsychoPy, you’ll need to delete its virtual environment folder, shortcuts, settings folder, and optionally, any dependencies installed for PsychoPy.

Removing the PsychoPy Virtual Environment Folder

By default, PsychoPy installs its files in the following locations:

• PsychoPy installation directory: /usr/local/psychopy/PsychoPy-${PSYCHOPY_VERSION}-Python${PYTHON_VERSION}
• PsychoPy's Python and wxPython: /usr/local/psychopy/python

To uninstall PsychoPy, delete:

sudo rm -rf /usr/local/psychopy

Remove the PsychoPy settings folder

PsychoPy stores its user-specific settings and preferences in the ~/.psychopy3 directory.

To remove it, run:

rm -rf ~/.psychopy3

Remove Desktop Shortcuts

The PsychoPy installer creates desktop shortcuts that you can safely delete. To remove all PsychoPy shortcuts, use:

rm ~/.local/share/applications/PsychoPy*.desktop
#rm ~/Desktop/PsychoPy*.desktop # Might be different if you do not have your language set to english

Remove PsychoPy from the System Path

During installation, a symbolic link to the PsychoPy executable is created in /usr/local/bin.
To remove it, run:

rm /usr/local/bin/PsychoPy*

Remove PsychoPy group and security limits

To remove the custom PsychoPy group and its associated security limits from your system, run:

sudo rm /etc/security/limits.d/99-psychopylimits.conf
sudo groupdel psychopy

(Optional): Remove Dependencies

Dependencies for PsychoPy and for building Python/WxPython are installed via package manager.

⚠ Warning ⚠: Removing dependencies can affect other applications. If you’re unsure, do not touch them.

Uninstall dependencies by package manager

Depending on the installation not all dependencies are installed. script_deps, fonts and psychopy_deps are always installed.

Here are all dependencies listed that might be installed:

apt-get
    script_deps=(curl git jq)
    psychopy_deps=(libasound2-dev libegl1-mesa-dev libglib2.0-dev libgtk-3-dev libnotify4 libusb-1.0-0-dev libwebkit2gtk-4.0-dev libwebkit2gtk-4.1-dev libxcb-cursor0 libxcb-xinerama0 libxkbcommon-x11-0 libsdl2-dev libglu1-mesa-dev portaudio19-dev pulseaudio pulseaudio-utils)
    fonts=(fonts-dejavu fonts-liberation fontconfig)
    python_build_deps=(build-essential libbz2-dev libffi-dev libreadline-dev libsqlite3-dev libssl-dev make xz-utils zlib1g-dev)
    wxpython_deps=(pkg‑config freeglut3-dev g++ gstreamer1.0-plugins-base gstreamer1.0-tools gstreamer1.0-x libgtk2.0-dev libjpeg-dev libnotify-dev libpng-dev libsm-dev libtiff-dev make)
    python_with_venv=(python3 python3-dev python3-pip python3-venv)

yum | dnf
    script_deps=(curl git jq)
    psychopy_deps=(alsa-lib-devel gtk3-devel libnotify mesa-libEGL-devel mesa-libGLU-devel portaudio-devel pulseaudio pulseaudio-utils SDL2-devel webkit2gtk3-devel webkit2gtk4.0-devel libusb1-devel)
    fonts=(fontconfig dejavu-sans-fonts dejavu-serif-fonts liberation-sans-fonts liberation-serif-fonts liberation-mono-fonts)
    python_build_deps=(bzip2-devel gcc libffi-devel make openssl-devel readline-devel sqlite-devel xz-devel zlib-devel)
    wxpython_deps=(pkgconfig freeglut-devel gcc-c++ gstreamer1-devel gtk2-devel libSM-devel libjpeg-devel libjpeg-turbo-devel libnotify-devel libpng-devel libtiff-devel make glib2-devel)
    python_with_venv=(python3 python3-devel python3-pip python3-venv)

pacman
    script_deps=(curl git jq)
    psychopy_deps=(alsa-lib gtk3 libnotify libusb mesa portaudio pulseaudio pulseaudio-utils SDL2 webkit2gtk xcb-util-cursor libxcb glu)
    fonts=(ttf-dejavu ttf-liberation noto-fonts gnu-free-fonts)
    python_build_deps=(base-devel bzip2 libffi make openssl readline sqlite xz zlib)
    wxpython_deps=(pkgconf freeglut gcc glib2 gstreamer gtk2 libjpeg libpng libsm libtiff make mesa)
    python_with_venv=(python python-pip python-virtualenv)

zypper
    script_deps=(curl git jq)
    psychopy_deps=(alsa-devel gtk3-devel libnotify4 libusb-1_0-devel libxcb-xinerama0 portaudio-devel pulseaudio pulseaudio-utils SDL2-devel)
    fonts=(dejavu-fonts liberation-fonts fontconfig)
    python_build_deps=(gcc libffi-devel libopenssl-devel make readline-devel sqlite3-devel xz-devel zlib-devel)
    wxpython_deps=(pkgconf‑pkg‑config freeglut-devel gcc-c++ glib2-devel gstreamer-plugins-base libSM-devel libjpeg-turbo libnotify-devel libpng16-devel make libtiff-devel)
    python_with_venv=(python3 python3-devel python3-pip python3-virtualenv)

Troubleshooting

• Ensure your package manager is working and not locked by another process.
• If prebuilt wheels fail, use --build=python, --build=wxpython, or --build=both to build from source.
• Make sure /tmp has enough space when building wxPython.
• Review the log file (path shown in the terminal) for details on errors.
• Before opening a new issue, search existing GitHub issues to see if your problem is already reported or resolved.

Contributing & Support

• Contributions, bug reports, and feature requests are welcome. Please fork the repository and submit a pull request.
• For help or to report issues, use the GitHub issue tracker and include the relevant log file.
• For general PsychoPy questions, visit the PsychoPy forums or the PsychoPy GitHub repository.

---