Docker Pass vs Docker Secret: What Is the Difference?

If you have been working with Docker secrets locally, you may have noticed two commands that sound similar but behave very differently: docker pass and docker secret.

At first glance, both appear to solve the same problem: keeping sensitive values such as API keys, tokens, and database passwords out of your source code. But they are designed for different environments and different workflows.

The short version is this:

docker pass is a local developer secret helper. docker secret is Docker Swarm's built-in runtime secret mechanism.

Let's unpack the difference.

What is docker pass?

docker pass is a Docker CLI plugin for managing local secrets. It stores secrets in your local machine's keychain or secret store, then lets Docker inject those secrets into containers.

A simple example:

docker pass set GH_TOKEN=abc123

Then you can pass that secret into a container:

docker run -e GH_TOKEN= busybox env

Or explicitly map a stored secret to a different environment variable name:

docker run -e GITHUB_TOKEN=se://GH_TOKEN busybox env

Conceptually, this flow looks like:

local keychain -> docker pass -> container environment variable

This makes docker pass useful for local development, demos, and developer workstations where you want to avoid putting secrets in shell history, .env files, or Compose files.

What is docker secret?

docker secret is Docker's built-in secret feature for Docker Swarm.

You create a secret like this:

printf "abc123" | docker secret create gh_token -

Then attach it to a Swarm service:

docker service create \
  --name demo \
  --secret gh_token \
  busybox \
  sleep 3600

Inside the container, the secret is exposed as a file:

/run/secrets/gh_token

Conceptually, the flow is:

Docker Swarm encrypted secret store -> service container file

This is not meant for regular one-off docker run containers. It is designed for Swarm-managed services.

Side-by-side comparison

Area	docker pass	docker secret
Primary use case	Local development secrets	Docker Swarm service secrets
Storage location	Local OS keychain or local secret store	Swarm encrypted Raft store
Scope	Single developer machine	Swarm cluster
Works with docker run	Yes	Not directly
Works with Docker Compose	Yes, with se://... references where supported	Mostly with Swarm stack deployments
Runtime exposure	Usually environment variables	Files under /run/secrets/...
Best fit	Local dev and demos	Swarm-based deployments

The biggest practical difference

If you are running containers like this:

docker run ...

then docker pass is usually the better fit.

If you are running services like this:

docker service create ...
docker stack deploy ...

then docker secret is the right Docker-native option.

That distinction matters because docker secret depends on Swarm. If you are not using Swarm, you generally will not get much value from docker secret.

Security considerations

docker secret is usually safer at runtime because secrets are mounted as files rather than passed as environment variables. Environment variables can be easier to expose accidentally through logs, diagnostics, crash dumps, process inspection, or application telemetry.

That does not mean docker pass is bad. It just means it is solving a different problem. It helps developers avoid hardcoding secrets locally, but once those secrets are injected as environment variables, your application still needs to treat them carefully.

A good rule of thumb:

• Use docker pass to improve local developer experience.
• Use platform-native secret integration for production.
• Avoid long-lived secrets in environment variables when a better runtime option exists.

Which one should you choose?

Use docker pass when:

• You are working locally.
• You use docker run or local Compose workflows.
• You want to avoid storing secrets in plain-text files.
• You want a lightweight way to inject secrets into containers.

Use docker secret when:

• You are using Docker Swarm.
• You deploy services with docker service create or docker stack deploy.
• You want secrets mounted as files under /run/secrets.
• Your runtime is managed by Swarm.

Final takeaway

The names are similar, but the responsibilities are different.

docker pass is about making local secret handling easier for developers.
docker secret is about distributing secrets securely to Swarm services.

And when you are running production workloads on Azure, Azure Key Vault and Managed Identity should be the preferred foundation.

A simple mental model:

Local Docker development: docker pass
Docker Swarm services: docker secret
Azure production workloads: Azure Key Vault + Managed Identity

Choose the tool based on where the container is running, not just based on the word "secret" in the command name.