Installation

This page is specifically for SPPAS-5. Click here if you want the SPPAS-4 installation manual.

Install Python

Before installing SPPAS, make sure Python is installed and works on your computer.

Use Python 3.9, 3.10, 3.11, or 3.12.
Install only one version of Python.
Use an official Python release. Do not use Anaconda.
Do not install Python 3.13 or newer.

Windows

Open the Microsoft Store and search for Python 3. Choose the application published by the Python Software Foundation. Click "Obtain".

macOS

Check whether Python is already installed, or install an official version of Python 3.

Linux

Python is often already installed. Ensure it's a right version. If needed, install it with your package manager.

Then, install 'venv':

 sudo apt install python3-venv

To check that it works, open a Terminal:

python3 --version

or:

python --version

If Python does not work, or if it's not the expected version, do not continue. Fix Python first, then install SPPAS.

This link to RealPython can be helpful: "How to Install Python on Your System: A Guide"

Install other dependencies (Linux Only)

To enable some of the features, the following system packages must be installed manually via the OS package manager:

For 'Alignment': julius > 4.2
For 'Formants': Praat
For 'Speech-To-Text': ffmpeg
For 'wxPython': libgtk-3-dev libglib2.0-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libwebkit2gtk-4.1-dev

Notice that the given package versions are the ones for Pop!_OS 24.04 distribution.

Install SPPAS

Step 1 — Download the SPPAS package

Download the latest version of SPPAS from the download page.

Step 2 — Unzip the package

The downloaded file is compressed. You must extract it before using SPPAS.

Example of unzip procedure — If you don't know how to extract a ZIP file, see this short tutorial.

Once extracted, you will obtain a folder containing the SPPAS files.

Important recommendations

Place the SPPAS folder inside your user directory.
Each user must have their own installation of SPPAS.
Make sure you have write permissions for this folder.
Do not use sppas as the folder name.
Avoid spaces and special characters in the folder path.

Configure SPPAS

Step 1 — Start your default web browser

SPPAS Dashboard uses your default web browser. It was tested with Firefox only; other browsers are not guaranteed. You should make Firefox your default web browser.

Note that Firefox is currently the only usable web browser listed in the recommended free software for French public agencies.

Step 2 — Start SPPAS

Open the SPPAS folder and run the file named sppas:

Windows → double-click sppas.bat (Windows batch file)
macOS → double-click sppas (Application)
Linux → double-click sppas.sh (Run in Terminal)

At the first launch, SPPAS creates its Python environment and installs the required dependencies. A terminal window will open and display the installation progress. This step may take several minutes. Do not close the Terminal.

When the initialization is finished, SPPAS automatically opens the Dashboard in your web browser.

Step 3 — Open the Setup application

SPPAS is now running, but some features are not yet installed.

In the Dashboard, click the Launch button of the Setup card.

The Setup app allows you to install:

third-party programs required by some features,
additional language resources,
large models used by some annotations,
optional SPPAS spin-off modules.

The Setup app can be launched again at any time from the Dashboard to install additional components.

Step 4 — Restart SPPAS

After running the Setup app, close SPPAS and start it again.

The new components will then be available in the interface.

Troubleshooting — Manual installation

If the automatic configuration does not work, you may want to check the FAQ first. Many common issues and questions are answered there. You can also install SPPAS manually by following the steps below and copying the commands exactly.

Step 1 — Open a terminal

Windows: open Command Prompt or PowerShell
macOS: open Terminal
Linux: open your terminal application

Step 2 — Go to the SPPAS folder

Example:

cd path/to/sppas

You can copy/paste the exact path from your file explorer.

Step 3 — Create the Python environment

 cd sppas-code
 python3 sppasinstall.py

If these commands work, SPPAS is correctly installed. You can then run it normally using the sppas launcher.

Advanced users — Setup from the terminal

If you prefer using the terminal instead of the graphical Setup app, you can install all optional components with sppassetup.py. This installs the exact same components as the Setup app: third-party programs, language resources, models, and spin-offs.

See Step 2 of the next section for details.

Install 'sppas' from PyPI

SPPAS can be installed directly from PyPI, without downloading the ZIP package. This is the recommended approach for developers using SPPAS as a Python library.

Step 1 — Install the package

pip install sppas

Step 2 — Install optional components

Run sppassetup.py to enable additional features. Use --help to list all available options.

Examples:

python sppassetup.py --eng

Installs linguistic resources for American English annotations.

python sppassetup.py --video

Enables annotations requiring image and video processing.

python sppassetup.py --facemark

Installs face detection models for the Face Detection annotator.