Great question. In Prefect 3.x there are two places where Docker registry auth matters: 1) when you build/push your flow image during deployment, and 2) when your worker pulls that image at run time. Here’s how to set up both. A) Building/pushing images (on your deploy machine) - Prefect uses your local Docker daemon for build/push. Just authenticate Docker like you normally do before running your deployment:

# Docker Hub
docker login

# GHCR
docker login <http://ghcr.io|ghcr.io>

# AWS ECR (example)
aws ecr get-login-password --region <region> \
| docker login --username AWS --password-stdin <aws_account_id>.dkr.ecr.<region>.<http://amazonaws.com|amazonaws.com>

- Then deploy with an image name in your registry and push enabled, e.g.:

flow.from_source("<https://github.com/org/repo>", entrypoint="flows/my_flow.py:my_flow").deploy(
  name="prod",
  work_pool_name="docker-pool",
  image="<http://ghcr.io/org/prefect-flow:latest|ghcr.io/org/prefect-flow:latest>",
  push=True,
)

If Docker can push the image from your shell, Prefect will be able to as well. B) Pulling images (on your worker machine) You have two options: Option 1 — Docker is already logged in on the worker host (simplest) - Make sure the machine running the Docker worker can pull the image:

docker login <your-registry>
docker pull <your-registry>/<repo>:<tag>

- Start your worker as usual:

prefect worker start -p docker-pool

If the host can pull the image, the worker can too. Option 2 — Use a Docker Registry Credentials block (managed via Prefect) This is useful when you don’t want to rely on

docker login

on the host. 1) Install the Docker integration and register blocks:

pip install "prefect[docker]"
# or with uv:
uv run --with 'prefect[docker]' prefect block register -m prefect_docker.credentials

2) Create a DockerRegistryCredentials block (UI or Python): - UI: Prefect UI -> Blocks -> + Create block -> “Docker Registry Credentials” -> fill in

registry_url

,

username

,

password

- Python:

from prefect_docker.credentials import DockerRegistryCredentials

creds = DockerRegistryCredentials(
  registry_url="<https://ghcr.io>",  # or your registry url
  username="YOUR_USERNAME",
  password="YOUR_TOKEN_OR_PASSWORD",
)
creds.save("my-registry-creds", overwrite=True)

3) Attach the credentials to your Docker work pool: - UI: Work Pools -> your Docker pool -> Default job variables -> set: - Image: your fully qualified image (e.g., ghcr.io/org/prefect-flow:latest) - Registry credentials: select the “my-registry-creds” block you created Now the worker will use these credentials to pull private images. Troubleshooting tips - If pulls fail on the worker, first test

docker pull <image>

directly on the worker host — if that fails, fix Docker auth there. - For GHCR, use a PAT with the appropriate read:packages scope. - For ECR, the login token expires; make sure your login step runs in the environment that starts the worker or periodically refresh it. - If your worker itself runs in a container, ensure it has access to the host Docker daemon (e.g., mount

/var/run/docker.sock

) or supply registry credentials via the block as above. Docs - Docker deployments/how-to: Docker infrastructure in Prefect 3 - Prefect YAML / deployments: prefect.yaml guide - Storing flow code: Store flow code A couple of quick clarifications to tailor the exact steps: - Are you trying to push an image during deploy, or just have the worker pull a private image at runtime? - Which registry are you using (Docker Hub, GHCR, ECR, GCR, etc.)? - Are you running a Docker work pool/worker, or another execution environment (e.g., Kubernetes)?