How to Use docker exec to Access and Manage Containers

Introduction

Docker is a containerization tool that helps developers create and manage portable, consistent Linux containers.

When developing or deploying containers you’ll often need to look inside a running container to inspect its current state or debug a problem. To this end, Docker provides the docker exec command to run programs in already running containers.

In this tutorial, we will learn about the docker exec command and how to use it to run commands and get an interactive shell in a Docker container.

Prerequisites

This tutorial assumes you already have Docker installed and your user has permission to run docker. If you need to run docker as the root user, please remember to prepend sudo to the commands in this tutorial.

For more information on using Docker without sudo access, please see the Executing the Docker Command Without Sudo section of our How To Install Docker tutorial.

Starting a Test Container

To use the docker exec command, you will need a running Docker container. If you don’t already have a container, start a test container with the following docker run command:

docker run -d --name container-name alpine watch "date >> /var/log/date.log"

This command creates a new Docker container from the official alpine image. This is a popular Linux container image that uses Alpine Linux, a lightweight, minimal Linux distribution.

We use the -d flag to detach the container from our terminal and run it in the background. --name container-name will name the container container-name. You could choose any name you like here, or leave this off entirely to have Docker automatically generate a unique name for the new container.

Next we have alpine, which specifies the image we want to use for the container.

And finally, we have watch "date >> /var/log/date.log". This is the command we want to run in the container. watch will repeatedly run the command you give it, every two seconds by default. The command that watch will run in this case is date >> /var/log/date.log. date prints the current date and time, like this:

Output
Fri Jul 23 14:57:05 UTC 2021

The >> /var/log/date.log portion of the command redirects the output from date and appends it to the file /var/log/date.log. Every two seconds a new line will be appended to the file, and after a few seconds it will look something like this:

Output
Fri Jul 23 15:00:26 UTC 2021
Fri Jul 23 15:00:28 UTC 2021
Fri Jul 23 15:00:30 UTC 2021
Fri Jul 23 15:00:32 UTC 2021
Fri Jul 23 15:00:34 UTC 2021

In the next step, we’ll learn how to find the names of Docker containers. This will be useful if you already have a container you’re targeting but are not sure what its name is.

Finding the Name of a Docker Container

We’ll need to provide docker exec with the name (or container ID) of the container we want to work with. We can find this information using the docker ps command:

docker ps

This command lists all of the Docker containers running on the server, and provides some high-level information about them:

Output
CONTAINER ID   IMAGE     COMMAND                  CREATED          STATUS          PORTS     NAMES
76aded7112d4   alpine    "watch 'date >> /var…"   11 seconds ago   Up 10 seconds             container-name

In this example, the container ID and name are highlighted. You may use either to tell docker exec which container to use.

If you’d like to rename your container, use the docker rename command:

docker rename container-name new-name

Next, we’ll run several examples of using docker exec to execute commands in a Docker container.

Running an Interactive Shell in a Docker Container

If you need to start an interactive shell inside a Docker Container, perhaps to explore the filesystem or debug running processes, use docker exec with the -i and -t flags.

The -i flag keeps input open to the container, and the -t flag creates a pseudo-terminal to which the shell can attach. These flags can be combined like this:

docker exec -it container-name sh

This will run the sh shell in the specified container, giving you a basic shell prompt. To exit back out of the container, type exit then press ENTER:

exit

If your container image includes a more advanced shell such as bash, you could replace sh with bash above.

Running a Non-interactive Command in a Docker Container

If you need to run a command inside a running Docker container, but don’t need any interactivity, use the docker exec command without any flags:

docker exec container-name tail /var/log/date.log

This command will run tail /var/log/date.log on the container-name container, and output the results. By default, the tail command will print out the last ten lines of a file. If you’re running the demo container we set up in the first section, you will see something like this:

Output
Mon Jul 26 14:39:33 UTC 2021
Mon Jul 26 14:39:35 UTC 2021
Mon Jul 26 14:39:37 UTC 2021
Mon Jul 26 14:39:39 UTC 2021
Mon Jul 26 14:39:41 UTC 2021
Mon Jul 26 14:39:43 UTC 2021
Mon Jul 26 14:39:45 UTC 2021
Mon Jul 26 14:39:47 UTC 2021
Mon Jul 26 14:39:49 UTC 2021
Mon Jul 26 14:39:51 UTC 2021

This is essentially the same as opening up an interactive shell for the Docker container (as done in the previous step with docker exec -it container-name sh) and then running the tail /var/log/date.log command. However, rather than opening up a shell, running the command, and then closing the shell, this command returns that same output in a single command without opening up a pseudo-terminal.

Running Commands in an Alternate Directory in a Docker Container

To run a command in a certain directory of your container, use the --workdir flag to specify the directory:

docker exec --workdir /tmp container-name pwd

This example command sets the /tmp directory as the working directory, then runs the pwd command, which prints out the present working directory:

Output
/tmp

The pwd command has confirmed that the working directory is /tmp.

Running Commands as a Different User in a Docker Container

To run a command as a different user inside your container, add the --user flag:

docker exec --user guest container-name whoami

This will use the guest user to run the whoami command in the container. The whoami command prints out the current user’s username:

Output
guest

The whoami command confirms that the container’s current user is guest.

Passing Environment Variables into a Docker Container

Sometimes you need to pass environment variables into a container along with the command to run. The -e flag lets you specify an environment variable:

docker exec -e TEST=sammy container-name env

This command sets the TEST environment variable to equal sammy, then runs the env command inside the container. The env command then prints out all the environment variables:

Output
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOSTNAME=76aded7112d4
TEST=sammy
HOME=/root

The TEST variable is set to sammy.

To set multiple variables, repeat the -e flag for each one:

docker exec -e TEST=sammy -e ENVIRONMENT=prod container-name env

If you’d like to pass in a file full of environment variables you can do that with the --env-file flag.

First, make the file with a text editor. We’ll open a new file with nano here, but you can use any editor you’re comfortable with:

nano .env

We’re using .env as the filename, as that’s a popular standard for using these sorts of files to manage information outside of version control.

Write your KEY=value variables into the file, one per line, like the following:

TEST=sammy
ENVIRONMENT=prod

Save and close the file. To save the file and exit nano, press CTRL+O, then ENTER to save, then CTRL+X to exit.

Now run the docker exec command, specifying the correct filename after --env-file:

docker exec --env-file .env container-name env

Output
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOSTNAME=76aded7112d4
TEST=sammy
ENVIRONMENT=prod
HOME=/root

The two variables in the file are set.

You may specify multiple files by using multiple --env-file flags. If the variables in the files overlap each other, whichever file was listed last in the command will override the previous files.

Common Errors and Debugging

When using the docker exec command, you may encounter a few common errors and issues. Here are some common errors and their solutions:

Error: “Container not found”

Error: No such container: container-name

The No such container error means the specified container does not exist, and may indicate a misspelled container name. Use docker ps to list your running containers and double-check the name.

Error: “Permission denied”

Error response from daemon: Permission denied

The Permission denied error typically occurs when the user running the docker exec command does not have sufficient permissions to access the container. Ensure that the user has the necessary permissions or run the command with sudo.

Error: “Container is not running”

Error response from daemon: Container 2a94aae70ea5dc92a12e30b13d0613dd6ca5919174d73e62e29cb0f79db6e4ab is not running

This error message indicates that the specified container exists, but it is not currently running. This can happen if the container was previously started and then stopped, or if it crashed or exited due to an error. To resolve this issue, you can start the container again using the docker start command, followed by the name of the container:

docker start container-name

Once you’ve started the container, you should be able to execute commands within it using docker exec.

Error: “Container is paused”

Error response from daemon: Container container-name is paused, unpause the container before exec

The Container is paused error indicates that the specified container is currently in a paused state. This means that the container is not running, but it is not stopped either. Before you can execute commands within the container, you need to unpause it using the docker unpause container-name command.

Fixes for common issues when using docker exec

To avoid common issues when using docker exec, ensure that:

• The container name is correct and the container is running.
• The user running the command has sufficient permissions.
• The container is not paused.
• The command is correctly formatted and the options are used correctly.

Performance Optimization: Tips for Ensuring docker exec Does Not Slow Down Your Container’s Performance

When running heavy commands using docker exec, it’s essential to ensure that the command execution does not significantly impact the performance of your container. Here are some tips to help you optimize the performance of your container when using docker exec:

• Use the --detach flag: When running a command that takes a long time to complete, use the --detach flag to detach the command from the terminal. This allows the command to run in the background, freeing up your terminal for other tasks. For example:

  docker exec --detach container-name command
  

• Limit resource usage: Use the --cpu-shares and --memory flags to limit the amount of CPU and memory resources allocated to the command. This ensures that the command does not consume excessive resources, potentially slowing down your container. For example:

  docker exec --cpu-shares 512 --memory 512m container-name command
  

• Optimize your command: Optimize the command you’re running to reduce its execution time. This might involve splitting a large task into smaller, more manageable parts or using more efficient algorithms. For example:

  docker exec container-name optimized-command
  

• Use a separate container for heavy tasks: If you have a task that requires significant resources or processing power, consider running it in a separate container. This isolates the task from your main container, ensuring that it does not impact the performance of your main application. For example:

  docker run --name heavy-task-container heavy-task-image
  

• Monitor container performance: Regularly monitor the performance of your container to identify potential bottlenecks or areas for optimization. This can be done using tools like docker stats or third-party monitoring solutions. For example:

  docker stats container-name
  

• Avoid running unnecessary commands: Only run commands that are necessary for your application’s operation. Avoid running unnecessary or redundant commands that can slow down your container. For example:

  docker exec container-name necessary-command
  

• Use Docker’s built-in performance features: Docker provides features like --oom-kill-disable to prevent the kernel from killing your container due to out-of-memory errors. Use these features to optimize the performance of your container. For example:

  docker run --oom-kill-disable container-name
  

By following these tips, you can ensure that running heavy commands using docker exec does not significantly impact the performance of your container.

FAQs

What is the docker exec command?

The docker exec command is a Docker command that allows you to run a command inside a running Docker container. It provides a way to execute a command in a container that is already running, without having to start a new container. This is particularly useful for debugging, inspecting, or modifying the state of a running container.

For example, to run a simple ls command inside a running container, you would use the following command:

docker exec <container-name> ls

This command will execute the ls command inside the container and display the output in your terminal.

How do I access the shell of a running container using docker exec?

To access the shell of a running container using docker exec, you can use the -it flags. The -i flag allows you to interact with the container, and the -t flag allocates a pseudo-TTY to the container. This allows you to interact with the container as if you were sitting in front of it.

Here’s an example of how to access the shell of a running container:

docker exec -it <container-name> bash

This command will open a new shell session inside the container, allowing you to interact with it as if you were logged in directly.

Can I run commands as a specific user inside a Docker container?

Yes, you can run commands as a specific user inside a Docker container using the --user flag. This flag allows you to specify the user ID or name to use when running the command.

For example, to run a command as the root user inside a container, you would use the following command:

docker exec --user root <container-name> command

This command will execute the specified command inside the container as the root user.

How do I run multiple commands inside a container using docker exec?

To run multiple commands inside a container using docker exec, you can use the -c flag followed by the commands you want to execute. The commands should be separated by semicolons.

Here’s an example of how to run multiple commands inside a container:

docker exec <container-name> -c "command1; command2; command3"

This command will execute command1, command2, and command3 sequentially inside the container.

What should I do if docker exec does not work?

If docker exec does not work as expected, there are a few things you can try to troubleshoot the issue:

1. Check the container status: Ensure that the container is running by using docker ps. If the container is not running, start it using docker start.
2. Verify the container name: Make sure you are using the correct container name or ID. You can list all running containers using docker ps to verify the name.
3. Check the command syntax: Ensure that the command you are trying to execute is correct and properly formatted.
4. Check the container’s configuration: If you are trying to execute a command that requires specific permissions or access, ensure that the container is configured to allow it.
5. Check the Docker version: Ensure that you are running a compatible version of Docker. You can check the Docker version using docker --version.

If none of these steps resolve the issue, you may want to consult the Docker documentation or seek further assistance from a Docker expert.

Conclusion

In this tutorial we learned how to execute commands in a running Docker container, along with some command line options available when doing so.

For more information on Docker in general, please see our Docker tag page, which has links to Docker tutorials, Docker-related Q&A pages, and more.

For help with installing Docker, take a look at How To Install and Use Docker on Ubuntu.

Next, you might want to explore more advanced Docker topics. Here are some tutorials to follow:

• Working with Docker Containers.
• How to Debug and Fix Common Docker Issues.
• How to Share Data Between the Docker Container and the Host.