docs/source/guide/install.md
Install Label Studio on premises or in the cloud. Choose the installation method that works best for your environment:
Label Studio is also available an enterprise product, which you can explore instantly through a free trial.
{% insertmd includes/deploy.md %}
Label Studio is tested with the latest version of Google Chrome.
If using other web browsers, or older versions of supported web browsers, unexpected behavior could occur.
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.
To install Label Studio with pip and a virtual environment, you need Python version 3.8 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.8 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.
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 humansignal/tap
Execute the following command to install Label Studio:
brew install humansignal/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.
!!! note
If you've previously installed the brew tap from the now-deprecated organization name heartexlabs/tap, we've got good news. You don't have to worry about migrating immediately. The deprecated tap has been set up as a mirror for humansignal/tap. This ensures continuity and minimizes disruptions for existing users.
Label Studio is also available as a Docker container. Make sure you have Docker installed on your machine.
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.
Or for Windows, you have to modify the volumes paths set by -v option.
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
If you want to build a local image, run:
docker build -t heartexlabs/label-studio:latest .
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.
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.
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
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/HumanSignal/label-studio.git
# install dependencies
cd label-studio
pip install poetry
poetry install
# run db migrations
poetry run python label_studio/manage.py migrate
# collect static files
poetry run python label_studio/manage.py collectstatic
# start the server in development mode at http://localhost:8080
poetry run python label_studio/manage.py runserver
conda create --name label-studio
conda activate label-studio
conda install psycopg2 # required for LS 1.7.2 only
pip install 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.