# podman push: Push Images to a Registry

> podman push uploads a local image to a registry. Reference for destination references, --creds, --tls-verify, and the auth and name errors in CI.

Source: https://latchkey.dev/learn/command-reference/podman-push  
Updated: 2026-06-30

podman push uploads a local image to a container registry under the destination reference you give.

After a build, podman push ships the image to a registry. The destination must be fully qualified, and the tag must already point at the image you want to send.

## What it does

podman push uploads the layers and manifest of a local image to the destination registry reference. The local image must be tagged with a name that includes the target registry, or you can give the destination as a second argument.

## Common usage

```Terminal
podman push ghcr.io/owner/app:1.2.3
# push a local tag to an explicit destination
podman push myapp:latest ghcr.io/owner/app:latest
podman push --creds user:token registry.example.com/team/app:1.0
podman push docker.io/owner/app:latest docker://docker.io/owner/app:latest
```

## Options

| Flag | What it does |
| --- | --- |
| --creds <user:pass> | Credentials for the destination registry |
| --authfile <path> | Use a specific auth file |
| --tls-verify=false | Skip TLS verification (test registries only) |
| --digestfile <path> | Write the pushed manifest digest to a file |
| --format <oci|v2s2> | Manifest format (oci or Docker v2s2) |
| --remove-signatures | Strip signatures before pushing |

## In CI

Tag with the full destination before pushing, then podman login once so the credentials are reused. Some registries (older Docker Hub mirrors, ECR) expect the Docker v2s2 manifest; pass --format v2s2 if a push is rejected for an unsupported OCI manifest.

## Common errors in CI

"unauthorized: authentication required" or "denied: requested access to the resource is denied" means missing or wrong credentials, or pushing to a repo you cannot write; run podman login and check the namespace. "manifest unknown" or "unsupported manifest media type" usually means the registry wants --format v2s2. "short-name ... no resolution" means the destination is unqualified; include the registry host.

## FAQ

### podman push: Push Images to a Registry?

After a build, podman push ships the image to a registry. The destination must be fully qualified, and the tag must already point at the image you want to send.

### What it does?

podman push uploads the layers and manifest of a local image to the destination registry reference. The local image must be tagged with a name that includes the target registry, or you can give the destination as a second argument.

### In CI?

Tag with the full destination before pushing, then podman login once so the credentials are reused. Some registries (older Docker Hub mirrors, ECR) expect the Docker v2s2 manifest; pass --format v2s2 if a push is rejected for an unsupported OCI manifest.

### Common errors in CI?

"unauthorized: authentication required" or "denied: requested access to the resource is denied" means missing or wrong credentials, or pushing to a repo you cannot write; run podman login and check the namespace. "manifest unknown" or "unsupported manifest media type" usually means the registry wants --format v2s2. "short-name ...

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt