• Docs >
  • Build Configuration (Advanced)

Build Configuration (Advanced)

Audience: Users who want full control over the docker image that is being installed in the cloud.

Level: Advanced

Advanced users who need full control over the environment a LightningWork runs in can specify a custom docker image that will be deployed in the cloud.

Use a docker image

Create a BuildConfig and provide a publicly accessible link to where the image is hosted:

from lightning.app import LightningWork, BuildConfig

class MyWork(LightningWork):
    def __init__(self):

        # Using a publicly hosted docker image:
        self.cloud_build_config = BuildConfig(
            # This is one of the base images Lightning uses by default

        # Can also be combined with extra requirements
        self.cloud_build_config = BuildConfig(image="...", requirements=["torchmetrics"])


Many public hosters like DockerHub apply rate limits for public images. We recommend to pull images from your own registry. For example, you can set up a docker registry on GitHub.


  • The build config only applies when running in the cloud and gets ignored otherwise. A local build config is currently not supported.

  • Images from private registries are currently not supported.


Custom docker images must have python installed. We’ll use virtualenv from this system python to create a virtual environment. We’ll also configure the virtualenv to use the packages installed under system’s python so your packages are not lost

Provide a docker file


Not yet supported. Coming soon.