> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beam.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://hub.docker.com/search?q=), [Google Artifact Registry](https://cloud.google.com/artifact-registry), [ECR](https://aws.amazon.com/ecr/), [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry), [NVIDIA](https://catalog.ngc.nvidia.com/containers) and more.

Just supply a `base_image` argument to [`Image`](/v2/reference/py-sdk#image).

```python theme={null}
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__}
```

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

## Private Docker Registries

Beam supports importing images from the following private registries: [AWS ECR](https://aws.amazon.com/ecr/), [Google Artifact Registry](https://cloud.google.com/artifact-registry), [Docker Hub](https://hub.docker.com/), [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry), and [NVIDIA Container Registry](https://catalog.ngc.nvidia.com/containers).

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:

```python theme={null}
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:

```python theme={null}
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.

<Tip>
  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.
</Tip>

```python theme={null}
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.

```sh theme={null}
export GCP_ACCESS_TOKEN=$(gcloud auth print-access-token --project=my-project)
```

Then configure the Image object to use the environment variable.

```python theme={null}
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.

```sh theme={null}
export NGC_API_KEY=abc123
```

Then configure the Image object to use the environment variable.

```python theme={null}
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.

```sh theme={null}
export DOCKERHUB_USERNAME=user123
export DOCKERHUB_PASSWORD=pass123
```

Then configure the Image object with those environment variables.

```python theme={null}
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](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry).

```sh theme={null}
export GITHUB_USERNAME=user123
export GITHUB_TOKEN=token123
```

Then configure the Image object with those environment variables.

```python theme={null}
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
```