The Docker Archive documentation is deprecated

The old workflow described in these docs will not be supported with new Lightly Worker versions above 2.6. Please switch to our new documentation page instead.


The docker container 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 ref-authentication-token as if you would use lightly. The token will be used to authenticate your account. The authentication happens at every run of the container. Make sure the docker container has a working internet connection and has access to

Download the Docker Image

Ask your account manager from Lightly for the credentials to download the docker container.

In short, installing the Docker container 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:

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


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.

Sanity Check

Finally, verify the correctness of the docker container by running the following command:

docker run --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!

Head on to First Steps to see how to sample your dataset!

Update Lightly Docker

To update the docker 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