Custom Registries

Beam supports importing images from custom public and private registries.

Public Docker Registries

You can import existing images from remote Docker registries, like Docker Hub, Google Artifact Registry, ECR, GitHub Container Registry, NVIDIA and more. Just supply a base_image argument to Image.

from beam import endpoint, Image

image = (
    Image(
        base_image="docker.io/nvidia/cuda:12.3.1-runtime-ubuntu20.04",
        python_version="python3.9",
    )
    .add_commands(["apt-get update -y", "apt-get install neovim -y"])
    .add_python_packages(["torch"])
)


@endpoint(image=image)
def handler():
    import torch

    return {"torch_version": torch.__version__}

Beam only supports Debian-based images. In addition, make sure your image is built for the correct x86 architecture.

Private Docker Registries

Beam supports importing images from the following private registries: AWS ECR, Google Artifact Registry, Docker Hub, GitHub Container Registry, and NVIDIA Container Registry. Private registries require credentials, and you can pass the credentials to Beam in two ways: as a dictionary, or exported from your shell so Beam can automatically lookup the values. Passing Credentials as a Dictionary You can provide the values for the registry as a dictionary directly, like this:

from beam import Image


image = Image(
    base_image="111111111111.dkr.ecr.us-east-1.amazonaws.com/my-app:latest",
    base_image_creds={
      "AWS_ACCESS_KEY_ID": "xxxx",
      "AWS_SECRET_ACCESS_KEY": "xxxx",
      "AWS_REGION": "xxxx"
    },
)

Passing Credentials from your Environment Alternatively, you can export your credentials in your shell and pass the environment variable names to base_image_creds as a list:

from beam import Image


image = Image(
    base_image="111111111111.dkr.ecr.us-east-1.amazonaws.com/my-app:latest",
    base_image_creds=[
        "AWS_ACCESS_KEY_ID",
        "AWS_SECRET_ACCESS_KEY",
        "AWS_SESSION_TOKEN",
        "AWS_REGION"
    ],
)

AWS ECR

To use a private image from Amazon ECR, export your AWS environment variables. Then configure the Image object with those environment variables.

You can authenticate with either your static AWS credentials or an AWS STS token. If you use the AWS STS token, your AWS_SESSION_TOKEN key must also be set.

from beam import Image

image = Image(
    python_version="python3.12",
    base_image="111111111111.dkr.ecr.us-east-1.amazonaws.com/my-image:latest",
    base_image_creds=["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION"]
)

@endpoint(image=image)
def handler():
    pass

GCP Artifact Registry

To use a private image from Google Artifact Registry, export your access token.

export GCP_ACCESS_TOKEN=$(gcloud auth print-access-token --project=my-project)

Then configure the Image object to use the environment variable.

from beam import Image

image = Image(
    python_version="python3.12",
    base_image="us-east4-docker.pkg.dev/my-project/my-repo/my-image:0.1.0",
    base_image_creds=["GCP_ACCESS_TOKEN"]
)

@endpoint(image=image)
def handler():
    pass

NVIDIA GPU Cloud (NGC)

To use a private image from NVIDIA GPU Cloud, export your API key.

export NGC_API_KEY=abc123

Then configure the Image object to use the environment variable.

from beam import Image

image = Image(
    python_version="python3.12",
    base_image="nvcr.io/nvidia/tensorrt:24.10-py3",
    base_image_creds=["NGC_API_KEY"]
)

@endpoint(image=image)
def handler():
    pass

Docker Hub

To use a private image from Docker Hub, export your Docker Hub credentials.

export DOCKERHUB_USERNAME=user123
export DOCKERHUB_PASSWORD=pass123

Then configure the Image object with those environment variables.

from beam import Image

image = Image(
    python_version="python3.12",
    base_image="docker.io/my-org/my-image:0.1.0",
    base_image_creds=["DOCKERHUB_USERNAME", "DOCKERHUB_PASSWORD"]
)

@endpoint(image=image)
def handler():
    pass

GitHub Container Registry

To use a private image from GitHub Container Registry, export your GitHub credentials. You will need a personal access token.

export GITHUB_USERNAME=user123
export GITHUB_TOKEN=token123

Then configure the Image object with those environment variables.

from beam import Image

image = Image(
    python_version="python3.12",
    base_image="ghcr.io/my-username/my-image:0.1.0",
    base_image_creds=["GITHUB_USERNAME", "GITHUB_TOKEN"]
)

@endpoint(image=image)
def handler():
    pass

​Public Docker Registries

​Private Docker Registries

​AWS ECR

​GCP Artifact Registry

​NVIDIA GPU Cloud (NGC)

​Docker Hub

​GitHub Container Registry

Public Docker Registries

Private Docker Registries

AWS ECR

GCP Artifact Registry

NVIDIA GPU Cloud (NGC)

Docker Hub

GitHub Container Registry