Private registries

Modal provides the Image.from_registry function, which pulls most common images available from public registries, like Docker Hub and GitHub Container Registry.

We also support private image registries, starting with AWS Elastic Container Registry (ECR) and GCP Artifact Registry.

Elastic Container Registry (ECR)

You can pull images from your AWS ECR account by specifying the full image URI as follows:

aws_secret = modal.Secret.from_name("my-aws-secret")
image = (
        .pip_install("torch", "huggingface")

stub = modal.Stub(image=image)

As shown above, you also need to use a Modal Secret containing the environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION. The AWS IAM user account associated with those keys must have access to the private registry you want to access.

The user needs to have the following read-only policies:

  "Version": "2012-10-17",
  "Statement": [
      "Action": ["ecr:GetAuthorizationToken"],
      "Effect": "Allow",
      "Resource": "*"
      "Effect": "Allow",
      "Action": [
      "Resource": "<MY-REGISTRY-ARN>"

You can use the IAM configuration above as a template for creating an IAM user. You can then generate an access key and create a Modal Secret using the AWS integration option. Modal will use your access keys to generate an ephemeral ECR token. That token is only used to pull image layers at the time a new image is built. We don’t store this token but will cache the image once it has been pulled.

Images on ECR must be private and follow image configuration requirements.