`docker cp -a` docs incorrect

[cspotcode]

Description

Is this a docs issue?

• My issue is about the documentation content or website

Type of issue

Information is incorrect

Description

Docs for docker cp -a claim that -a will "Archive mode (copy all uid/gid information)"

My testing shows that this is incorrect.

It appears that docker cp . container-name:/ without the -a flag will preserve ownership of the copied files. That is, a file owned by user ID 1234 on the host will be created with user ID 1234 within the container.

Adding the -a flag will instead change the ownership of copied files to match the --user of the container.

Location

https://docs.docker.com/engine/reference/commandline/cp/

Suggestion

No response

Reproduce

Expected behavior

No response

docker version

-

docker info

-

Additional Info

Re-posted here per this comment on the original docker/docs issue: docker/docs#17533 (comment)

[hiSandog]

To pin down whether this is a docs bug or a code bug: historically docker cp -a (archive mode) is meant to preserve UID/GID, so your finding — that without -a ownership is preserved and with -a it's re-mapped to the container's --user — is the opposite of the documented intent and would be surprising behavior, not just a wording slip.

Could you share the docker version and a minimal repro (source file owned by a known uid, the exact docker cp invocation, and the resulting ls -l inside the container)? That'll tell us whether -a is genuinely re-mapping ownership (code bug) or whether the no--a preservation you're seeing is the quirk worth documenting. Either way the current "copy all uid/gid information" wording for -a doesn't match what you observed.

[cspotcode]

#!/usr/bin/env bash
set -euo pipefail

docker pull alpine:latest
docker run -d --name repro --user nobody alpine:latest sleep 300

echo "test" > /tmp/testfile.txt
sudo chown 1234:5678 /tmp/testfile.txt

echo
echo "=== Docker version ==="
docker --version
docker version
echo

echo "=== host ownership ==="
ls -ln /tmp/testfile.txt
echo

docker exec repro mkdir -p /tmp/repro/no_a /tmp/repro/a

echo "=== no -a ==="
docker cp /tmp/testfile.txt repro:/tmp/repro/docker-cp.txt
docker exec repro ls -ln /tmp/repro/docker-cp.txt
echo

echo "=== with -a ==="
docker cp -a /tmp/testfile.txt repro:/tmp/repro/docker-cp-with-dash-a.txt
docker exec repro ls -ln /tmp/repro/docker-cp-with-dash-a.txt
echo

docker rm -f repro
sudo rm /tmp/testfile.txt

❯ ./docker-cp-repro.sh
latest: Pulling from library/alpine
Digest: sha256:28bd5fe8b56d1bd048e5babf5b10710ebe0bae67db86916198a6eec434943f8b
Status: Image is up to date for alpine:latest
docker.io/library/alpine:latest
0e5ac03c105c48020b9de0083592706c9904a5988f0c837899bcd06393656459

=== Docker version ===
Docker version 29.5.3, build d1c06ef
Client:
 Version:           29.5.3
 API version:       1.54
 Go version:        go1.26.4
 Git commit:        d1c06ef
 Built:             Wed Jun  3 17:59:16 2026
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Desktop 4.79.0 (230596)
 Engine:
  Version:          29.5.3
  API version:      1.54 (minimum version 1.40)
  Go version:       go1.26.4
  Git commit:       285b471
  Built:            Wed Jun  3 17:59:56 2026
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          v2.2.5
  GitCommit:        e53c7c1516c3b2bff98eb76f1f4117477e6f4e66
 runc:
  Version:          1.3.6
  GitCommit:        v1.3.6-0-g491b69ba
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

=== host ownership ===
-rw-r--r-- 1 1234 5678 5 Jun 30 12:02 /tmp/testfile.txt

=== no -a ===
Successfully copied 5B (transferred 2.05kB) to repro:/tmp/repro/docker-cp.txt
-rw-r--r--    1 1234     5678             5 Jun 30 16:02 /tmp/repro/docker-cp.txt

=== with -a ===
Successfully copied 5B (transferred 2.05kB) to repro:/tmp/repro/docker-cp-with-dash-a.txt
-rw-r--r--    1 65534    65534            5 Jun 30 16:02 /tmp/repro/docker-cp-with-dash-a.txt

repro

Emphasis:

-rw-r--r--    1 1234     5678             5 Jun 30 16:02 /tmp/repro/docker-cp.txt
-rw-r--r--    1 65534    65534            5 Jun 30 16:02 /tmp/repro/docker-cp-with-dash-a.txt