PsychoPy Installation Script for Linux

---

This script automates the installation of PsychoPy on a wide range of Linux distributions, handling all dependencies and environment setup for you.

Recommended: PsychoPy Studio, PsychoPy's new app. It sets up Python and PsychoPy on its own and drops wxPython entirely, so there are no long wxPython builds or dependency issues:

bash <(curl -LsSf https://github.com/wieluk/psychopy_linux_installer/releases/latest/download/psychopy_linux_installer) --studio

Compared to downloading the AppImage yourself, this also installs the system libraries it needs (e.g. libfuse2), adds a desktop shortcut and a terminal command, falls back to running without FUSE if mounting fails, and includes an uninstaller.

Table of Contents

1. Supported and Tested Distributions
2. Usage
3. Options
4. Examples
5. How the Installer Works
6. Post-Installation
7. Uninstalling PsychoPy
8. Troubleshooting
9. Contributing & Support

Supported and Tested Distributions

The installer has been tested and confirmed to work on the following Linux distributions:

• Ubuntu: 26.04, 24.04, 22.04
• Pop!_OS: 22.04
• Debian: 13, 12
• Fedora: 44
• Linux Mint: 22
• openSUSE Leap: 16
• Arch Linux: rolling (Arch-based distributions such as Manjaro use its wheels)

While these distributions are tested, the script is designed to be compatible with other Linux distributions as well.

Usage

Install curl with your package manager if it is not already installed.

Option 1: One-line Install

Run the installer directly without saving it to disk:

• GUI Mode (requires curl and zenity):

  bash <(curl -LsSf https://github.com/wieluk/psychopy_linux_installer/releases/latest/download/psychopy_linux_installer) --gui

• Command-Line Mode:

  bash <(curl -LsSf https://github.com/wieluk/psychopy_linux_installer/releases/latest/download/psychopy_linux_installer)

• PsychoPy Studio Mode (lightweight: no Python/wxPython, just an AppImage):

  bash <(curl -LsSf https://github.com/wieluk/psychopy_linux_installer/releases/latest/download/psychopy_linux_installer) --studio

Option 2: Download Script for Reuse

1. Download the installer script:

   curl -LOsSf 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 (requires curl and zenity):

     ./psychopy_linux_installer --gui

   • Command-Line Mode:

     ./psychopy_linux_installer

   • PsychoPy Studio Mode:

     ./psychopy_linux_installer --studio

Options

Option	Description	Default
--psychopy-version=VERSION	Specify the PsychoPy version to install (e.g. 2024.2.4, latest, or git).	latest
--psychopy-app-version=VERSION	Specify the PsychoPy App (classic GUI) version. Only used from PsychoPy 2026.2.0 onward, where the GUI lives in the separate psychopy_app package. Versioned independently from --psychopy-version since psychopy-app releases lag behind psychopy on PyPI.	latest
--python-version=[3.8.x|3.9.x|3.10.x]	Choose the Python version for the PsychoPy environment. Patch version is optional.	3.10
--wxpython-version=VERSION	Specify the wxPython version to install (e.g. 4.3.1). Python 3.8/3.9 installs default to 4.2.1, the newest version with prebuilt wheels for them.	4.3.1
--build-wxpython	Force building wxPython from source instead of downloading prebuilt wheels, even if wheels are available.	false
--wxpython-wheel-index=URL	Provide a custom URL for wxPython wheels. Useful for rolling distributions (e.g., Arch) or distributions that can use wheels built for another compatible system (e.g., Ubuntu-based). Example: --wxpython-wheel-index= https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-24.04/	(none)
--install-dir=DIR	Set the installation directory for PsychoPy.	/opt/psychopy
--target-users=USER1,USER2,...|*	Comma-separated users to install for, or '*' for all real users. Adds users to psychopy group and creates symlink/shortcuts	current user
--venv-name=NAME	Set a custom name for the virtual environment folder.	PsychoPy-${PSYCHOPY_VERSION}-Python${PYTHON_VERSION}
--additional-packages=PKG,PKG,…	List extra pip packages to install (comma-separated, supports package==version). Example: --additional-packages=psychopy_bids,seedir,psychopy-crs==0.0.2	(none)
--requirements-file=FILE	Install all pip packages listed in the given requirements file into the PsychoPy environment.	(none)
--sudo-mode=[ask|auto|error|continue|force]	Control how sudo is used for system commands: ask: Prompt each time sudo is needed. auto: Use sudo automatically when required. error: Exit if sudo is needed. continue: Skip commands needing sudo. force: Always use sudo, even if not strictly necessary.	ask
--non-interactive	Run unattended; sets --sudo-mode=auto unless specified.	false
--desktop-shortcuts=LIST|all|none	Shortcuts to create. Comma-separated list of: psychopy, builder, coder. Use all for all three, none for no shortcuts.	psychopy
--disable-path	Do not create a symlink in /usr/local/bin or ~/.local/bin.	false
--remove-psychopy-settings	Delete existing PsychoPy user settings at ~/.psychopy3 during installation.	false
--no-fonts	Skip installation of additional font packages.	false
--cleanup	Removes build packages, uv cache and locally built wxPython wheels after installation. Warning: Setting this may cause non-admin installations to fail after this main installation.	false
--studio	Install PsychoPy Studio (a self-contained AppImage) instead of the classic Python/wxPython app. No Python, venv, or wxPython is installed; Studio manages its own Python environment internally. Offered as an option when --psychopy-version resolves to 2026.1.0 or later (see Notes below); the classic app remains the default even then. Cannot be combined with --psychopy-version, --psychopy-app-version, --python-version, --wxpython-version, --build-wxpython, --wxpython-wheel-index, --additional-packages, --requirements-file, --no-fonts, or --remove-psychopy-settings. Passing any of these together with --studio is an error.	false
--studio-version=VERSION	Specify the PsychoPy Studio version to install (e.g. 2026.1.2, or latest). Only valid together with --studio.	latest
--remove-studio-settings	Delete existing PsychoPy Studio settings at ~/.config/psychopy4 during installation. Only valid together with --studio.	false
--gui	Launch the graphical installer (ignores other command-line options).	false
-f, --force-overwrite	Overwrite the target install folder if it already exists.	false
--log-level=LEVEL	Set the log level. Valid values: debug, info, warning, error. debug shows full command output.	info
--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 --install-dir=~/psychopy option enables non-admin users to upgrade or reinstall if the 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.
• If requirements.txt contains relative paths to wheel files, the wheels folder must be in the same directory as requirements.txt.
• PsychoPy Studio: PsychoPy Studio (an Electron-based replacement for the classic app) is available from PsychoPy 2026.1.0 onward, versioned independently via --studio-version (default latest). It is unrelated to --psychopy-version, which classic-app installs use instead. Starting with PsychoPy 2026.2.0, the classic desktop app's GUI code additionally moved to a separate psychopy_app package. The classic app remains the default install for any version. If --psychopy-version resolves to 2026.1.0 or later and --studio wasn't passed, interactive installs are offered a choice between the two (choosing Studio installs the Studio release of that same version); --non-interactive installs default to the classic app. Pass --studio explicitly to install PsychoPy Studio instead.

Examples

bash <(curl -LsSf https://github.com/wieluk/psychopy_linux_installer/releases/latest/download/psychopy_linux_installer) --psychopy-version=2024.2.4 --python-version=3.10 --install-dir=/home/ubuntu/psychopy --venv-name=custom-psychopy --additional-packages=psychopy_bids,seedir,psychopy-crs==0.0.2 --sudo-mode=auto

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

How the Installer Works

• Detects your Linux distribution and package manager (supports apt, yum, dnf, pacman, and zypper).
• Installs all necessary system dependencies for PsychoPy and wxPython.
• Installs uv (a fast Python package manager) and uses it to install the specified Python version (3.8, 3.9, or 3.10).
• Sets up the PsychoPy installation directory at ${INSTALL_DIR}/PsychoPy-${PSYCHOPY_VERSION}-Python${PYTHON_VERSION} (default: /opt/psychopy). You can customize this with --install-dir and --venv-name.
• Creates a virtual environment and installs wxPython (downloads prebuilt wheels, tries GitHub releases, or builds from source if needed), logging a warning for each fallback tier it has to skip past.
• Upgrades pip and required Python packages, then installs the specified PsychoPy version.
• Adds user to psychopy group and sets security limits.
• Generates a startup wrapper script (start_psychopy) with uninstaller (--unistall).
• Optionally creates a desktop shortcut and a symbolic link in /usr/local/bin/ or ~/local/bin.
• Logs all actions to a file (initially in /tmp, then moved to the install directory). Use --log-level=debug for detailed terminal output.
• --studio mode skips all of the above except distro/package-manager detection, the install directory, the desktop shortcut, and the PATH symlink. It downloads the PsychoPy Studio AppImage (self-contained; it manages its own Python environment internally) plus a small set of runtime libraries (notably libfuse2, needed for the AppImage to self-mount) instead of installing Python, wxPython, or PsychoPy itself.

Notes:

• If prebuilt wxPython wheels are unavailable for your distribution, the script will attempt to build from source.
• Building wxPython from source may take significant time and require extra disk space; the installer checks free (not total) /tmp space and offers to increase it if it's low.

Post-Installation

After installation, a desktop shortcut for the main PsychoPy application will be created by default. Use --desktop-shortcuts=all to also create Builder and Coder shortcuts, or --desktop-shortcuts=none to skip shortcut creation. The application will also 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 uninstall PsychoPy using the automated uninstaller, run the start_psychopy wrapper script with the --uninstall flag.

You can do this in two ways:

• Using the absolute path (default install directory and venv name):

  /opt/psychopy/PsychoPy-${PSYCHOPY_VERSION}-Python${PYTHON_VERSION}/start_psychopy --uninstall

  (If you used a custom --install-dir and/or --venv-name, adjust the path accordingly.)

• If the PsychoPy wrapper is in your system PATH (symlinked as VENV_NAME):

  ${VENV_NAME} --uninstall

  (By default, ${VENV_NAME} is PsychoPy-${PSYCHOPY_VERSION}-Python${PYTHON_VERSION} unless you set a custom name.)

During uninstallation, you may be prompted to remove additional files and settings, such as:

• /etc/security/limits.d/99-psychopylimits.conf
• the psychopy group
• user settings at ~/.psychopy3
• the uv binary and related data
• python versions installed by uv
• installed packages that have been added by psychopy_linux_installer

If you have other PsychoPy environments installed on your system, it is recommended to answer "n" to these prompts to avoid affecting other installations.

Note: --studio installs have no Python, uv, group, or ~/.psychopy3 settings to clean up, so they skip those prompts. They are instead prompted to remove PsychoPy Studio's own settings at ~/.config/psychopy4.

Troubleshooting

• Ensure your package manager is working and not locked by another process.
• If prebuilt wheels fail, use --build-wxpython 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.

---