Kubernetes

Kubectl cp – How to Copy File From Pod to Local (5 Examples)

kubectl cp

🚀 Level Up Your Infrastructure Skills

You focus on building. We’ll keep you updated. Get curated infrastructure insights that help you make smarter decisions.

The kubectl cp command lets you easily copy files and directories between your local machine and a Kubernetes pod. It’s a simple but powerful way to move data without setting up shared volumes or rebuilding images.

In this article, we will look at the kubectl cp command, its definition, and syntax, before showing how to use it to perform practical everyday tasks, such as copying files from a pod to your local system. We will also take a look at some common errors associated with kubectl cp, explaining the common causes and how to go about troubleshooting them.

We will cover:

    1. What is the kubectl cp command
    2. How to use kubectl cp – examples
    3. How to troubleshoot kubectl cp errors
    4. Kubectl cp alternatives

What is the kubectl cp command?

The kubectl cp  is a command-line utility in Kubernetes used to copy files and directories to and from a container in a Kubernetes pod. It allows you to transfer files between your local system and a running container within a pod without needing to set up additional tools or services.

kubectl cp is only available for pods running a compatible version of the K8S API server (v1.14+). It can be a convenient way to transfer files in and out of containers when needed for troubleshooting, debugging, or data exchange.

kubectl cp command syntax

The example usage of the kubectl cp command is shown below:

kubectl cp <source> <destination> -n <namespace> <pod-name>:<path>
  • <source>: The source file or directory on your local system or in the container (use . to represent the current directory in the container).
  • <destination>: The destination on your local system or in the container.
  • -n <namespace>: Specifies the namespace in which the pod is running (optional).
  • <pod-name>: The name of the pod where you want to copy files.
  • <path>: The path within the container where you want to copy files or directories.

How to use kubectl cp — examples

Let’s look at some use case examples for the kubectl cp command.

Example 1. Copying files from pod to local system

To copy files from a pod to the local system use:

kubectl cp -n <namespace> <pod-name>:<path> <destination-on-local-system>

If the pod is in the default namespace, you can omit the <namespace>/ prefix. For example:

kubectl cp my-pod:/app/logs ./logs

For pods in a specific namespace use:

kubectl cp my-namespace/my-pod:/app/data ./data

For example, if you have a pod named “my-pod” in the “default” namespace and you want to copy a file named “file.txt” from the pod to your local system, you can use the following command:

kubectl cp -n default my-pod:/path/to/file.txt .

Note the . represents the current directory.

Example 2. Copying files from local system to pod

To copy files from your local system to a Kubernetes pod, use the kubectl cp command in the following format:

kubectl cp /local/path/to/file <namespace>/<pod-name>:/path/in/pod

If the pod is in the default namespace, omit the namespace:

kubectl cp ./myfile.txt my-pod:/app/myfile.txt

The kubectl cp command uses the Kubernetes API and tar under the hood to transfer files. Therefore, both your local system and the container image must have tar installed. If tar is missing in the container, the copy will fail with an error.

For example, if you have a pod named “my-pod” in the “default” namespace and you want to copy a file named “file.txt” from your local system to the pod, you can use the following command:

kubectl cp -n default . my-pod:/path/to/file.txt

Example 3. Copying files from a pod to a pod

To copy files directly from one Kubernetes pod to another, Kubernetes does not provide a built-in command. You must copy the files from the source pod to your local machine, then from your local machine to the destination pod.

For example, first copy from source pod to local:

kubectl cp <namespace>/<source-pod>:<source-path> <local-path>

And then copy from local to destination pod:

kubectl cp <local-path> <namespace>/<destination-pod>:<destination-path>

This two-step process works reliably, though it is not suitable for large-scale or automated transfers. For direct pod-to-pod file transfers, consider using a shared volume (e.g., PVC) or running a job inside the cluster with tools like rsync or scp if network policies allow.

Example 4. Copying files from a pod in a specific namespace to local system

The -n option in the kubectl cp command is used to point out a specific namespace.

kubectl cp -n <namespace> <pod-name>:<path> <destination-on-local-system>

For example, to copy file.txt from a pod named my-pod in the test namespace to the current local directory:

kubectl cp -n test my-pod:/path/to/file.txt .

Example 4. Copying directories

To copy directories using kubectl cp, use the -r flag to ensure recursive copying:

kubectl cp /local/path <namespace>/<pod-name>:/remote/path -c <container-name> -r

If copying from a pod to local, reverse the source and destination:

kubectl cp <namespace>/<pod-name>:/remote/path /local/path -c <container-name> -r

When multiple containers exist in the pod, make sure the directory paths are fully specified and the container name is included.

Without the -r (recursive) flag, kubectl cp will only copy individual files, not directories. If you attempt to copy a directory without -r, it will fail with an error like “tar: this does not look like a tar archive.”

Example 5. Copying from a specific container

kubectl cp does not support copying files directly between containers in the same pod. Instead, you must first copy the file from one container to your local machine, then copy it from your machine into the target container.

Copy from source container to local:

kubectl cp <pod-name>:<source-path> ./local-file -c <source-container>

And then copy from local to target container:

kubectl cp ./local-file <pod-name>:<target-path> -c <target-container>

This two-step process is required because kubectl cp uses the Kubernetes API, which does not support direct container-to-container file transfers within a pod. For frequent transfers, consider using shared volumes or kubectl exec with tar over a pipe.

How to troubleshoot kubectl cp errors

kubectl cp command errors can occur for various reasons, and troubleshooting them depends on the specific error message you encounter. Some common errors are described below.

Kubectl cp unexpected EOF error

The “unexpected EOF” error when using kubectl cp typically indicates that the kubectl cp command received an incomplete or unexpected response from the Kubernetes cluster. This can occur for various reasons but is commonly caused by network issues or unexpected interruptions in the transfer process.

How to fix it?

To resolve the issue, check the networking is configured correctly, that the cluster is healthy and responding correctly, and that the container and pod you are targeting are responding as expected. Also, check you have enough disk space available for the file transfer on the source and target.

Kubectl cp terminated with exit code 126

The “terminated with exit code 126” error when using kubectl cp usually indicates that the command failed because it was unable to find or execute a specific executable or script in the target container. Exit code 126 typically means “Permission denied”.

How to fix it?

To resolve the issue, check you have permissions on the file you’re trying to copy, that it is readable, or that the script you’re trying to run is executable. If the file or command you’re trying to access is not found in the specified path, you’ll encounter this error.

  • Double-check the paths and arguments in your kubectl cp command.
  • Verify that the file or command exists in the container.
  • Check the container is running and is responding correctly.
  • Also, check that the file you’re trying to copy or execute is in a compatible format with the container’s operating system. For example, a binary compiled for Linux won’t work in a Windows container.

Kubectl cp tar: command not found

This error occurs when the tar command is missing inside the container. kubectl cp relies on tar being available in both the local system and the target container to package and transfer files.

How to fix it?

Ensure that the container image includes the tar utility. If it doesn’t, you can:

  • Modify the Dockerfile to install tar (e.g., RUN apt-get install -y tar for Debian-based images).
  • Use an alternate method for file transfer, such as kubectl exec with base64 encoding.
  • Replace the container with a version that includes common utilities if you’re consistently needing file access.

Kubectl cp alternatives

When transferring large files to or from Kubernetes pods, kubectl cp can be slow or unreliable, so more efficient alternatives are often preferred for production use.

  1. rsync over kubectl exec or kubectl port-forward: rsync is faster and more reliable for large files or directories. You can set up an rsync server in the pod or use kubectl port-forward to expose an rsync port locally.
  2. tar with kubectl exec and stream redirection: You can archive and stream files into or out of the pod using commands like: tar cf - localdir | kubectl exec -i pod -- tar xf - -C /target This avoids base64 encoding overhead used in kubectl cp.
  3. Persistent Volume (PV) mounts: Attach a shared PV to both a utility pod and the target pod. Use a sidecar or a job to copy files directly into the volume, which is efficient for large datasets.
  4. S3-compatible object storage: Upload the file to S3 or MinIO, then use tools like aws-cli or mc inside the pod to download it. This offloads the transfer from the API server.

Managing Kubernetes with Spacelift

If you need help managing your Kubernetes projects, consider Spacelift. It brings with it a GitOps flow, so your Kubernetes Deployments are synced with your Kubernetes Stacks, and pull requests show you a preview of what they’re planning to change.

Fast-growing Brace wanted to streamline its infrastructure processes as its needs evolved. They chose Spacelift for its powerful and growing feature set. As a result, the company has accelerated its deployment processes while auditing–critically important in the financial services world–is now much more straightforward. Spacelift has helped Brace achieve a level of simplicity that makes life much easier for DevOps and developer teams alike.

Spacelift customer case study

Read the full story

With Spacelift, you get:

  • Policies to control what kind of resources engineers can create, what parameters they can have, how many approvals you need for a run, what kind of task you execute, what happens when a pull request is open, and where to send your notifications
  • Stack dependencies to build multi-infrastructure automation workflows with dependencies, having the ability to build a workflow that can combine Terraform with Kubernetes, Ansible, and other infrastructure-as-code (IaC) tools such as OpenTofu, Pulumi, and CloudFormation,
  • Self-service infrastructure via Blueprints enabling your developers to do what matters – developing application code while not sacrificing control
  • Creature comforts such as contexts (reusable containers for your environment variables, files, and hooks), and the ability to run arbitrary code
  • Drift detection and optional remediation

If you want to learn more about Spacelift, create a free account today or book a demo with one of our engineers.

Key points

The kubectl cp command can be used to transfer files and directories between your local machine and pods, or between pods running on your K8S cluster.

Manage Kubernetes easier and faster

Spacelift allows you to automate, audit, secure, and continuously deliver your infrastructure. It helps overcome common state management issues and adds several must-have features for infrastructure management.

Start free trial

Frequently asked questions

  • How to use kubectl cp with multiple containers in a pod?

    kubectl cp does not support copying files directly to or from a specific container in a multi-container pod. By default, it only interacts with the first container defined in the pod specification.

    To copy files to or from a specific container, you must use kubectl exec as a workaround, since kubectl cp does not include a --container flag. 

Kubernetes Commands Cheat Sheet

Grab our ultimate cheat sheet PDF

for all the kubectl commands you need.

k8s book
Share your data and download the cheat sheet