Troubleshoot installation issues

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


Starting with Label Studio 1.7.0 release, the application run using a non-root docker user with ID 1001.

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
[How to run a more secure non-root user container by Dan Wash](