Migrate a Label Studio instance to a new machine

Safely transfer a self-hosted instance of Label Studio from one machine to another, including all images, projects and annotations.

Label Studio is an open source data labelling platform that users can install within a Linux environment. It is used for a wide range of data labelling and annotation tasks when developing machine learning algorithms. Media can be uploaded into Label Studio and sorted into separate projects before annotations are coupled with those media to develop training sets. Problems arise when the Label Studio hosting environment needs to be replaced, such as when a user needs to upgrade machines. Exporting annotations is fairly straightforward, but what if you also need to retain the projects and labelled images too?

The Label Studio documentation doesn’t provide much detail, however it is possible to ‘clone’ a Label Studio instance from one machine to another.

For this methodology, I will assume that Label Studio is to be cloned into a clean version of Linux and that all images were uploaded within the user interface (ie not stored on a cloud somewhere). This has been tested with the Community Edition.

The steps are as follows:

Install key packages
Create a new Linux virtual environment
Install Label Studio and obtain file paths
Save your old Label Studio files to a zip
Transfer the zip to your new machine
Replace the Label Studio files on your new machine
Launch Label Studio on the new machine
Clean up

Step 1: Install key packages

The first step is to install some key packages into your new Linux machine via apt install:

sudo apt install software-properties-common
sudo apt install virtualenv
sudo apt install pkg-config
sudo apt install python3-dev
sudo apt install python3-pip
sudo apt install zip

Step 2: Create a new Linux virtual environment

Create a new virtual environment for Label Studio. If you want to do this with a custom version of Python, you can read the details in this blog post.

In my case, I want to install an environment called “labelstudio” running Python version 3.13:

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.13
sudo apt install python3.13-venv
sudo apt install python3.13-dev
virtualenv --python="/usr/bin/python3.13" "labelstudio"

Step 3: Install Label Studio and obtain file paths

Open your new environment and install Label Studio via pip:

source labelstudio/bin/activate
python -m pip install label-studio

Next, launch Label Studio by typing label-studio into the command line. The startup text will provide some useful information.

=> Database and media directory: /home/adamdimech/.local/share/label-studio
=> Static URL is set to: /static/
=> Database and media directory: /home/adamdimech/.local/share/label-studio
=> Static URL is set to: /static/
Read environment variables from: /home/adamdimech/.local/share/label-studio/.env

Note the file path.

Step 4: Save your old Label Studio files to a zip

Go to your old Label Studio machine and launch Label Studio in the same manner as above, to confirm the file paths. Note these.

Next, go to the directory location that contains the label-studio folder. In this example, the file paths on the old and new machines match:

cd /home/adamdimech/.local/share/

From this location, zip all of the files using the below command. I will save the zip file to my downloads directory.

zip -r ~/downloads/label-studio.zip label-studio

This will save all of the images uploaded into Label Studio along with all of their annotations and the SQLite database.

Step 5: Transfer the zip file to your new machine

Use whichever method is most suitable (such as FTP) to transfer your zip file to the new machine. If you need to transfer to a different Linux distribution on the same WSL2 machine, you can use this methodology.

Step 6: Replace the Label Studio files on the new machine

Return to your new Linux machine and go to the directory that contains label-studio, that was identified earlier.

cd /home/adamdimech/.local/share/

Rename the label-studio folder to something else, as a temporary back-up in case the transfer doesn’t work properly.

mv label-studio label-studio.old

Next, unzip the Label Studio files onto a temporary folder on your new machine (in this case, at ~/temp):

cd ~/
unzip /location/of/label-studio.zip -d temp

Copy the unzipped files into ~/.local/share:

cp -r  ~/temp/label-studio ~/.local/share

Step 7: Launch Label Studio on the new machine

Launch Label Studio on the new machine, log in (using the same credentials as on the old machine) and check that everything is in order.

Step 8: Clean up

On the new machine:

cd ~
rm -r temp
cd ~/.local/share
rm -r label-studio.old

On the old machine:

cd ~/downloads
rm label-studio.zip

Comments

One response to “Migrate a Label Studio instance to a new machine”

On 18 September 2025, Growagarden wrote:

Great, clear instructions for cloning Label Studio! Really helpful for backing up projects and images. Makes migration seem manageable.