Install and upgrade

Install Label Studio on premises or in the cloud. Choose the installation method that works best for your environment:

• Install with pip
• Install with Docker
• Install on Ubuntu
• Install from source
• Install with Anaconda
• Upgrade Label Studio

Label Studio is also available an enterprise product, which you can explore instantly through a free trial.

System requirements

You can install Label Studio on a Linux, Windows, or MacOSX machine running Python 3.6 or later.

Port requirements

Label Studio expects port 8080 to be open by default. To use a different port, specify it when starting Label Studio. See Start Label Studio.

Server requirements

Allocate disk space according to the amount of data you plan to label. As a benchmark, 1 million labeling tasks take up approximately 2.3GB on disk when using the SQLite database. 50GB of disk space is recommended for production instances.

Use a minimum of 8GB RAM, but 16GB RAM is recommended. for example, t3.large or t3.xlarge on Amazon AWS.

For more on using Label Studio at scale and labeling performance, see Start Label Studio.

Software requirements

PostgreSQL version 11.5 or SQLite version 3.35 or higher.

Web browser support

Label Studio is tested with the latest version of Google Chrome and is expected to work in the latest versions of:

• Google Chrome
• Apple Safari
• Mozilla Firefox

If using other web browsers, or older versions of supported web browsers, unexpected behavior could occur.

Install prerequisite

Install Label Studio in a clean Python environment. We highly recommend using a virtual environment (venv or conda) to reduce the likelihood of package conflicts or missing packages.

Install using pip

To install Label Studio with pip and a virtual environment, you need Python version 3.7 or later. Run the following:

python3 -m venv env
source env/bin/activate
python -m pip install label-studio

To install Label Studio with pip, you need Python version 3.7 or later. Run the following:

pip install label-studio

After you install Label Studio, start the server with the following command:

label-studio

The default web browser will automatically open at http://localhost:8080 with Label Studio. Please refer to start Label Studio for more options when starting Label Studio.

Install using Homebrew

To install Label Studio with Brew, you need to have Brew package manager installed on your system. If you do not have Brew installed, please visit brew.sh for installation instructions.

Execute the following command to add the Heartexlabs tap:

brew tap heartexlabs/tap

Execute the following command to install Label Studio:

brew install heartexlabs/tap/label-studio

After you install Label Studio, initiate the server using the following command:

label-studio

The default web browser will automatically open at http://localhost:8080 with Label Studio. Please refer to start Label Studio for more options when starting Label Studio.

Install with Docker

Label Studio is also available as a Docker container. Make sure you have Docker installed on your machine.

Install with Docker on *nix

To install and start Label Studio at http://localhost:8080, storing all labeling data in ./mydata directory, run the following:

docker run -it -p 8080:8080 -v $(pwd)/mydata:/label-studio/data heartexlabs/label-studio:latest

!!! attention “important”
As this is a non-root container, the mounted files and directories must have the proper permissions for the UID 1001.

Install with Docker on Windows

Or for Windows, you have to modify the volumes paths set by -v option.

Override the default Docker install

You can override the default Docker install by appending new arguments.

In Windows Command Line (cmd):

docker run -it -p 8080:8080 -v %cd%/mydata:/label-studio/data heartexlabs/label-studio:latest label-studio --log-level DEBUG

In PowerShell:

docker run -it -p 8080:8080 -v ${PWD}/mydata:/label-studio/data heartexlabs/label-studio:latest label-studio --log-level DEBUG

Build a local image with Docker

If you want to build a local image, run:

docker build -t heartexlabs/label-studio:latest .

Run with Docker Compose

Use Docker Compose to serve Label Studio at http://localhost:8080. You must use Docker Compose version 1.25.0 or higher.

Start Label Studio:

docker-compose up -d

This starts Label Studio with a PostgreSQL database backend. You can also use a PostgreSQL database without Docker Compose. See Set up database storage.

Install Label Studio without internet access

Download label-studio docker image (host with internet access and docker):

docker pull heartexlabs/label-studio:latest

Export it as a tar archive:

docker save heartexlabs/label-studio:latest | gzip > label_studio_latest.tar.gz

Transfer it to another VM:

scp label_studio_latest.tar.gz <ANOTHER_HOST>:/tmp

SSH into <ANOTHER_HOST> and import the archive:

docker image import /tmp/label_studio_latest.tar.gz

Follow steps from Install and Upgrade to run LS.

Install on Ubuntu

To install Label Studio on Ubuntu and run it in a virtual environment, run the following command:

python3 -m venv env
source env/bin/activate
sudo apt install python3.9-dev
python -m pip install label-studio

Install from source

If you want to use nightly builds or extend the functionality, consider downloading the source code using Git and running Label Studio locally:

git clone https://github.com/heartexlabs/label-studio.git
cd label-studio
# Install all package dependencies
pip install -e .
# Run database migrations
python label_studio/manage.py migrate
# Collect static files
python label_studio/manage.py collectstatic
# Start the server in development mode at http://localhost:8080
python label_studio/manage.py runserver

Install with Anaconda

conda create --name label-studio
conda activate label-studio
conda install psycopg2  # required for LS 1.7.2 only
pip install label-studio

Upgrade Label Studio

To upgrade to the latest version of Label Studio, reinstall or upgrade using pip.

pip install --upgrade label-studio

Migration scripts run when you upgrade to version 1.0.0 from version 0.9.1 or earlier.

To make sure an existing project gets migrated, when you start Label Studio, run the following command:

label-studio start path/to/old/project

The most important change to be aware of is changes to rename “completions” to “annotations”. See the updated JSON format for completed tasks.

If you customized the Label Studio Frontend, see the Frontend reference guide for required updates to maintain compatibility with version 1.0.0.

Troubleshoot installation

You might see errors when installing Label Studio. Follow these steps to resolve them.

Run the latest version of Label Studio

Many bugs might be fixed in patch releases or maintenance releases. Make sure you’re running the latest version of Label Studio by upgrading your installation before you start Label Studio.

Errors about missing packages

If you see errors about missing packages, install those packages and try to install Label Studio again. Make sure that you run Label Studio in a clean Python environment, such as a virtual environment.

For Windows users the default installation might fail to build the lxml package. Consider manually installing it from the unofficial Windows binaries. If you are running Windows 64-bit with Python 3.8 or later, run pip install lxml‑4.5.0‑cp38‑cp38‑win_amd64.whl to install it.

Errors from Label Studio

If you see any other errors during installation, try to rerun the installation.

pip install --ignore-installed label-studio

OpenBLAS blas_thread_init: pthread_create failed for thread X of Y: Operation not permitted

Upgrade Docker Engine to the latest available version(>= 20.10.12).

PermissionError: [Errno 13] Permission denied: /label-studio/data/media

You may already be aware that Docker containers generally operate with root privileges by default. This unrestricted container management permits actions like installing system packages, modifying configuration files, and binding privileged ports, which are all beneficial for development purposes. However, this can lead to significant risks when containers are deployed in a production environment.

This is because anyone who gains access to your root-running container could initiate undesirable processes, such as injecting malicious code. Running a process in your container as root also enables altering the user id (UID) or group id (GID) when launching the container, making your application more vulnerable.

It is advised to use non-root containers for the following reasons:

• Security: Non-root containers inherently offer better security. In the event of a container engine security issue, running the container as a non-privileged user will prevent malicious code from obtaining elevated permissions on the container host. For more information on Docker’s security features, refer to this guide.

• Platform limitations: Some Kubernetes distributions such as OpenShift, execute containers with random UUIDs. This method is incompatible with root containers, which must always run using the root user’s UUID. In these situations, only non-root container images will operate, making them a necessity.

Our Dockerfile contains the line USER 1001 which assigns a non-root user UID to the image, enabling the container to run as an unprivileged user. This implementation applies the security enhancements and other restrictions mentioned above to the container.

File permissions for non-root user

By default, Label Studio container images operate as non-root. As a result, any directory requiring write access must be assigned to the root group (GID 0). This ensures that the arbitrary user (default UID 1001) can write to the directory, as this user is always part of the root group. To achieve this, simply set the ownership of the local directory to the root group (GID 0), which will be enough regardless of the UID:

mkdir mydata
sudo chown :0 mydata