The Lightly worker currently reports usage metrics to our analytics software (we use mixpanel) which uses https encrypted GET and POST requests to The transmitted data includes information about crashes and the number of samples that have been filtered. However, the data does not include input / output samples, filenames, or any other information which can be sensitive to our customers.


The licensing and account management is done through the Authentication API Token as if you would use lightly. The token will be used to authenticate your account. The authentication happens at every run of the worker. Make sure the Lightly worker has a working internet connection and has access to

Download the Python client

We recommend to use the lightly Python package to interact with the Lightly API. It offers helper functions to create and delete datasets, schedule jobs, and access the results:

pip install lightly

See Installing Lightly for details.

Download the Lightly Worker

The Lightly worker comes as a Docker image. Ask your account manager from Lightly for the credentials to download the image.

In short, installing the Docker image consists of the following steps:

  1. Copy the container-credentials.json to the instance you want to use for filtering

  2. Authenticate Docker to download the Lightly image

  3. Pull the Docker image

  4. Check whether the container works

First, we need to access the private container registry of Lightly. You received a container-credentials.json file from your account manager.

Second, to be able to download the Docker image you need to log in with these credentials. The following command will authenticate your installed Docker account. We assume container-credentials.json is in your current directory.

cat container-credentials.json | docker login -u _json_key --password-stdin

If the above command does not work, try the following. And please make sure the json format is correct (no sudden newlines etc.):

cat container-credentials.json | docker login -u json_key --password-stdin


When docker is freshly installed only the root user can run Docker commands. There are two ways to work in this case.

  1. give your user permission to run - recommended docker (see

  2. run Docker commands as root (always replace docker with sudo docker) - functional but less secure

For example, to authenticate as non-root user you would run

cat container-credentials.json | sudo docker login -u _json_key --password-stdin

Third, after authentication you should be able to pull our latest image. Using the following command you pull the latest image from our European cloud server:

docker pull

In case you experience any issues pulling the docker image after successful authentication check out our FAQ section.


Until version 2.1.8 the latest image was named from version 2.2 onwards the image is now called Please make sure to update any old Docker run commands to use the new image name.

The downloaded image has a long name. We can reduce it by making use of docker tag. The following experiments are using the following image name lightly/worker:latest. Create a new Docker tag using the following command:

docker tag lightly/worker:latest


If you don’t want to tag the image name you can replace lightly/worker:latest by for all commands in this documentation.

Update the Lightly Worker

To update the Lightly worker we simply need to pull the latest docker image.

docker pull

Don’t forget to tag the image again after pulling it.

docker tag lightly/worker:latest


You can download a specific version of the Docker image by indicating the version number instead of latest. We follow semantic versioning standards.

Sanity Check

Next, verify that the Lightly worker is installed correctly by running the following command:

docker run --shm-size="1024m" --rm -it lightly/worker:latest sanity_check=True

You should see an output similar to this one:

[2022-05-02 20:37:27] Lightly Docker Solution v2.2.0
[2022-05-02 20:37:27] Congratulations! It looks like the Lightly container is running!

Register the Lightly Worker

Finally, start the Lightly worker in waiting mode. In this mode, the worker will long-poll the Lightly API for new jobs to process. To do so, a worker first needs to be registered.


You only have to register each worker once. The registry is required because it’s possible to have several workers registered at the same time working on different jobs in parallel.

# execute the following code once to get a worker_id
from lightly.api import ApiWorkflowClient

client = ApiWorkflowClient(token='MY_AWESOME_TOKEN') # replace this with your token
worker_id = client.register_compute_worker()

Store the worker_id in a secure location and then start the worker with

docker run --shm-size="1024m" --gpus all --rm -it \
    -v {OUTPUT_DIR}:/home/output_dir \
    lightly/worker:latest \
    token=MY_AWESOME_TOKEN \


All registered workers and their ids can be found under

All outputs generated by jobs will be stored in {OUTPUT_DIR}. The output directory will be explained in more detail in the First Steps.

[2022-06-03 07:57:34] Lightly Docker Solution v2.2.0
[2022-06-03 07:57:34] You are using docker build: Wed Jun  1 09:51:10 UTC 2022.
[2022-06-03 07:57:34] Starting worker with id 61f27c8bf2f5d06164071415
[2022-06-03 07:57:34] Worker started. Waiting for jobs...


In case the command fails because docker does not detect your GPU you want to make sure nvidia-docker is installed. You can follow the guide here.

Head on to First Steps to see how to schedule a job!