Create a repository

Create a private or public repository before you push to it, with tag immutability, a storage cap and tags set from the start.

Last updated 18 November 2026View as Markdown

A docker push to a name that has no repository yet creates one too (see Push an image); creating it first lets you choose its settings. Replace my-app with the repository name.

Prerequisites

  • Permission for ecr:CreateRepository. Without it the console's create page sends you back to the repository list.
  • The organization is below its repository quota (see Quotas).

Create the repository

  1. Open Container registry, then choose Create image repository.
  2. For Repository name, enter my-app.
  3. (Optional) For Description, enter a description.
  4. Under Who can pull, choose Private (the default) or Public.
  5. (Optional) Under Project and tags, set the repository's tags.
  6. Choose Create image repository.

The console sets name, description, visibility and tags. Tag immutability and a storage cap are set afterwards on the Settings tab, or here through the CLI, the API or Terraform.

Repository settings

Field Values Default
name 2–255 characters; see Repositories, tags and images required
description up to 256 characters none
visibility private, public private
tagMutability mutable, immutable mutable
tagMutabilityExclusions up to 10 tag patterns (* globs) that stay mutable none
storageQuotaBytes 1 MiB (1048576) to 1 PiB, or null no cap
tags key/value pairs none

The name cannot be changed later. In the console the description cannot be changed either; the API (PATCH /ecr/api/repositories/{id} with description) can.

Result

201 with the repository, its id included. The console opens the repository's page. Creating a repository costs nothing; you pay for the layers pushed into it.

If it is refused

  • 409 A repository named "my-app" already exists.
  • 409 with code QuotaExceeded when the organization is at its repository quota; the message starts with "Quota exceeded:".
  • 400 when a tag key your organization requires is missing, or when the project the repository is created in does not exist.
Did this page help you?