# amazon-ecr-credential-helper: Docker Credentials for ECR Without docker login

> A Docker credential helper that answers registry authentication from your existing AWS credentials. It removes the twelve-hour token chore from ECR workflows, and it stops working the moment your instance profile or SSO session cannot resolve.

**awslabs/amazon-ecr-credential-helper** — Automatically gets credentials for Amazon ECR on docker push/docker pull

- Repository: https://github.com/awslabs/amazon-ecr-credential-helper
- Stars: 2,719 · Forks: 351
- Language: Go
- License: Apache-2.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/awslabs-amazon-ecr-credential-helper

## The problem: ECR tokens expire and docker login does not remember them

Amazon ECR does not accept long-lived registry passwords. Authentication happens through a token that the AWS CLI or SDK obtains, and that token has a limited lifetime. The standard workaround is to run a command that retrieves the token and pipes it into docker login before every push or pull, or to schedule that command in a cron job and hope the schedule lines up with the deployment. Both approaches leave credentials in places people forget about: shell history, CI logs, a file on disk, or the Docker config of a shared build host.

The Amazon ECR Docker Credential Helper takes a different position. Instead of storing a token, it implements the Docker credential helper protocol, the same interface used by docker-credential-desktop and other helpers. When the Docker daemon needs credentials for a registry, it invokes the helper as a subprocess and the helper returns a username and password on demand. The README describes it as a credential helper for the Docker daemon that makes it easier to use Amazon Elastic Container Registry. The audience is anyone whose machines already authenticate to AWS through a profile, an EC2 or ECS instance role, or an SSO session, and who wants docker push and docker pull to work against ECR URLs without a separate token step. It is not a credential store. It is a translator between the AWS credential chain and the Docker registry authentication protocol.

## How the helper answers a pull: the Docker credential helper protocol

The mechanism is a naming convention plus a short-lived subprocess. Docker looks for an executable named docker-credential- plus the value of credsStore in ~/.docker/config.json. For this project, the installed binary is named docker-credential-ecr-login, so the matching configuration value is ecr-login. When the daemon needs to authenticate to a registry, it runs that binary with a get argument and the registry hostname on standard input, then reads a JSON object from standard output containing ServerURL, Username and Password.

The helper resolves AWS credentials through the normal chain, then calls the ECR GetAuthorizationToken API for the registry that was requested. The username and password it returns are derived from that token. Because the helper runs on demand, there is no stored secret to rotate and no file to leak: the token exists only in the Docker daemon's memory for the duration of the operation. The repository layout reflects this single purpose. The Go source lives under ecr-login/, the Makefile builds a binary named docker-credential-ecr-login into bin/local, and a Dockerfile based on golang:1.26-alpine exists so builds can run in a container with the host's UID and GID passed through. That is the whole architecture: one binary, one protocol, one AWS API call per registry.

## Installing amazon-ecr-credential-helper and configuring credsStore

Most users should install from a distribution package rather than build from source. The README lists commands for Amazon Linux, Debian, Ubuntu, Arch, Alpine, macOS and Windows. On Amazon Linux 2023 the package comes from the standard repositories:

```bash
sudo dnf install -y amazon-ecr-credential-helper
```

On Debian and Ubuntu the package name is the same, and the README shows an apt update followed by an apt install of amazon-ecr-credential-helper. On macOS the Homebrew formula is docker-credential-helper-ecr, so the install command is brew install docker-credential-helper-ecr. On Alpine the package is docker-credential-ecr-login, installed with apk add. Note that the package names differ from the binary name in several of these cases, which is a common source of confusion after installation.

Installing the package does not enable it. Docker has to be told which helper to use. The README's Configuration section covers Docker, AWS credentials and the helper itself; the Docker side is a credsStore entry in the Docker config file:

```json
{
  "credsStore": "ecr-login"
}
```

With that in place, a pull from an ECR registry should succeed without a preceding docker login, provided your AWS credentials resolve. The README also documents optional helper settings, including a flag that disables the use of the AWS profile and a proxy configuration, described in the Configuration section. Those matter on hosts where the default credential chain picks up a profile you do not want the helper to use.

If you prefer to build, the repository provides a Makefile. The default target builds a local binary, and the Makefile defines a docker target that runs the build inside the project's own container image:

```bash
make build
make docker
```

The first produces bin/local/docker-credential-ecr-login. The second runs the same build in the container defined by the repository's Dockerfile, which is useful when your host lacks the right Go toolchain. In both cases the output binary must end up on PATH under the name docker-credential-ecr-login, because that name is what Docker resolves from the credsStore value.

## Where it breaks: credential resolution, not the helper

The helper's failure modes are almost entirely failures of the AWS credential chain, and they present as Docker authentication errors rather than helpful AWS messages. If the machine has no instance role, no environment variables, no shared credentials file entry and no SSO session, the helper has nothing to exchange for a token, and the pull fails. On developer laptops the usual cause is an expired SSO session; on CI runners it is a missing role assumption. The README points readers to its Troubleshooting section for these cases, which is the right place to start, but the underlying issue is that the helper deliberately does not manage credentials. It consumes them.

There is a second boundary worth stating plainly: the helper only helps Docker. Tools that talk to registries without going through the Docker credential helper protocol will not pick it up. The README lists Kubernetes under its related material but the repository does not document a Kubernetes image pull secret integration, and the helper is not a substitute for one, because kubelet does not invoke Docker credential helpers. If your cluster pulls from ECR, you still need whatever mechanism your cluster uses; this project addresses the Docker daemon on the machine where it runs. A third limitation is environmental: the helper is a subprocess launched by the daemon, so it must be installed and configured for the user or service context that runs dockerd, not only for your interactive shell. Installing it with pip or a package manager under your own account and then running Docker as a different user is a configuration that looks correct and does not work.

## amazon-ecr-credential-helper compared with aws ecr get-login-password

The direct alternative is the AWS CLI's own token workflow: run aws ecr get-login-password, pipe the output into docker login with the registry URL, and repeat when the token expires. That approach is explicit and portable. It works on any machine with the AWS CLI installed, it needs no Docker configuration, and it is easy to reason about in a script. Its cost is that the token is a secret you now handle: it passes through a pipe, it may land in shell history if written carelessly, and it expires, so anything automated has to re-run the command on a schedule. On a fleet of build hosts, that scheduling is the part that breaks quietly.

The credential helper inverts those trade-offs. There is no token to schedule, because Docker asks for credentials each time it needs them, and nothing is written to disk. The price is a dependency on Docker's helper protocol and on the helper binary being present and correctly named on the host. On a machine where you push to ECR once a month, the CLI command is less machinery. On a machine that pulls base images on every build, the helper removes an entire category of scheduled job. There is also a middle ground the README does not discuss: some teams wrap the CLI command in a script and call it from a Makefile target. That works, but it is the workflow the helper exists to replace.

## Maintenance, release cadence and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-08-25. Recent releases are v0.12.0 on 2026-02-27, v0.11.0 on 2025-11-08 and v0.10.1 on 2025-06-30. That is a slow but non-zero cadence: roughly one release every few months, with commits in between. For a component this small, that is a reasonable signal, and the cost of upgrading is low because the interface is the Docker credential helper protocol rather than a project-specific API.

The practical upgrade cost is mostly packaging. Because the helper is distributed through distribution repositories, the version you get is the version your distribution ships, not the version on the project's release page. The README links to Repology badges for several distributions, which is the fastest way to see what each archive currently carries. If you need a specific release, building from source with the Makefile is the documented path. The project is licensed under Apache-2.0, and the repository includes a NOTICE file and a THIRD-PARTY-LICENSES file. Apache-2.0 is a permissive licence with an explicit patent grant and a notice requirement, but the details depend on how you redistribute the binary, and that is a question for your own legal review rather than something this article can settle.

## Conclusion

Adopt it if your hosts already hold AWS credentials through a profile, instance role or SSO session and you push or pull from ECR often enough that re-running aws ecr get-login-password has become a script you maintain. Do not adopt it as a way to give a machine ECR access it does not otherwise have: the helper only translates credentials that already resolve, so a host with no role and no profile gains nothing. Before rolling it out, verify that the binary lands on the PATH under the exact name docker-credential-ecr-login, that the credsStore value matches that name, and that your AWS credentials work without the helper first. Then confirm the credential helper logs in under the same user that runs the Docker daemon, because a helper configured only in your shell profile will be invisible to dockerd.

## FAQ

### How do I install amazon-ecr-credential-helper?

On Amazon Linux 2023 run sudo dnf install -y amazon-ecr-credential-helper, and on Debian or Ubuntu use apt to install the same package name. macOS users can install the community-maintained Homebrew formula docker-credential-helper-ecr, and Alpine uses apk add docker-credential-ecr-login. After installing, Docker still needs a credsStore entry in its config file.

### How do I use amazon-ecr-credential-helper with Docker?

Set credsStore to ecr-login in the Docker config file, which tells the daemon to invoke the installed docker-credential-ecr-login binary when it needs registry credentials. Once that is in place and your AWS credentials resolve, docker push and docker pull against an ECR registry work without a separate docker login step.

### How does authentication to Amazon ECR work with this helper?

The helper resolves credentials through the standard AWS credential chain and then obtains an ECR authorization token, returning the resulting username and password to the Docker daemon over the credential helper protocol. Because the token is fetched on demand, there is no stored registry password to rotate. If the AWS credential chain cannot resolve, the helper has nothing to exchange and the pull fails.

## Sources

- [awslabs/amazon-ecr-credential-helper on GitHub](https://github.com/awslabs/amazon-ecr-credential-helper)
- [Issues](https://github.com/awslabs/amazon-ecr-credential-helper/issues)
- [License: Apache-2.0](https://github.com/awslabs/amazon-ecr-credential-helper/blob/main/LICENSE)
- [README](https://github.com/awslabs/amazon-ecr-credential-helper/blob/main/README.md)
- [Releases](https://github.com/awslabs/amazon-ecr-credential-helper/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/awslabs-amazon-ecr-credential-helper