# Pull an image

Find an image's tag or digest and pull it, by tag or pinned to its digest.

Replace org-example1234.ecr.example.com with your registry host, my-app with the
repository name and repository-id with its id.

## Prerequisites

- Permission for `ecr:PullImage` on the repository. On a public repository a client that is not
  logged in pulls without it; a logged-in client is still judged by its policies.
- To list images: `ecr:ListImages` on the repository through the CLI or the API. In the console,
  `ecr:DescribeRepositories` on it; without it the repository's page answers 404.

## Find the image

**Console**
1. Open **Image repositories**, then open the repository.
2. On the **Images** tab, choose the image's row.

The row's detail shows a `docker pull` line per tag and **Pull by digest**. The tab reads the
newest 500 manifests; when there are more, older images are listed through the CLI or the API.

**CLI**
```sh
dcloud ecr images list repository-id --limit 100 --offset 0
```

**API**
```http
GET /ecr/api/repositories/repository-id/images?limit=100&offset=0
```

The list has one row per tag, `{ tag, manifest }`, newest image first, plus one row with
`tag: null` for each manifest no tag points at: an untagged image, and also each platform image
of a multi-platform image and each signature or SBOM. `hasMore` says whether there is another page. `limit` is 1–500
(100 by default). It carries no scan state; read that per image (see
[Scan an image](scan-an-image.md)).

## Pull

```sh
docker pull org-example1234.ecr.example.com/my-app:v1.2.0
docker pull org-example1234.ecr.example.com/my-app@sha256:<digest>
```

A pull by digest gets exactly that image, however its tags move later.

## If the pull is refused

- `DENIED` `token does not grant pull on repository my-app`: the credential may not pull this
  repository. Without credentials, a private repository answers `401` instead.
- `NAME_UNKNOWN` `repository name not known`: no repository has that name.
- `MANIFEST_UNKNOWN` `manifest unknown`: no image has that tag or digest. An image a lifecycle rule
  deleted answers the same, and the pull is noted on it (see
  [Restore an expired image](restore-an-expired-image.md)).

## Related

- [Make a repository public](make-a-repository-public.md)
- [Use a pull-through cache](use-a-pull-through-cache.md)
- `ecr.images.list` · `dcloud ecr images list`
