# kubectl cp: Usage, Options & Common CI Errors

> kubectl cp copies files between your machine and a container. The tar dependency, path syntax, and why cp fails on distroless images in CI.

Source: https://latchkey.dev/learn/command-reference/kubectl-cp  
Updated: 2026-06-25

Copy files into or out of a running container.

kubectl cp moves files between the local filesystem and a container, or between two containers. In CI it is used to pull a generated artifact (a coverage report, a built file) out of a pod, or push a fixture in.

## What it does

kubectl cp SRC DEST copies files, where a pod path is written namespace/pod:/path. It works by streaming a tar archive through the container, so the target container must have a tar binary on its PATH. -c selects the container in a multi-container pod.

## Common usage

```Terminal
kubectl cp my-pod:/app/report.xml ./report.xml      # out of the pod
kubectl cp ./fixture.json my-pod:/tmp/fixture.json   # into the pod
kubectl cp ./data my-ns/my-pod:/data -c app          # explicit ns + container
kubectl cp my-pod:/var/log ./logs                    # a whole directory
```

## Common errors in CI

"tar: not found" or "error: ... exec: \"tar\": executable file not found" is the defining failure: cp needs tar inside the container, and distroless/scratch/minimal images do not ship it. Work around it by adding tar to a debug image, or stream instead: kubectl exec my-pod -- cat /app/report.xml > report.xml for a single file. Also note cp does not preserve into a path whose parent does not exist - create the directory first, and beware that absolute vs relative path mistakes silently copy to the wrong place.

## Using this in CI

A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.

```Terminal
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods

# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info

# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### kubectl cp: Usage, Options & Common CI Errors?

kubectl cp moves files between the local filesystem and a container, or between two containers. In CI it is used to pull a generated artifact (a coverage report, a built file) out of a pod, or push a fixture in.

### What it does?

kubectl cp SRC DEST copies files, where a pod path is written namespace/pod:/path. It works by streaming a tar archive through the container, so the target container must have a tar binary on its PATH. -c selects the container in a multi-container pod.

### Common errors in CI?

"tar: not found" or "error: ... exec: \"tar\": executable file not found" is the defining failure: cp needs tar inside the container, and distroless/scratch/minimal images do not ship it. Work around it by adding tar to a debug image, or stream instead: kubectl exec my-pod -- cat /app/report.xml > report.xml for a single file.

---

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