docker exec Command: Syntax, Options, Examples

The docker exec command enables the user to execute commands within a running Docker container. It is used for interacting with applications and services that run inside a container without stopping the container's operation.

This article will show you how to use the docker exec command as a direct interface for debugging, administering, and monitoring containerized processes.

Prerequisites

• Docker installed.
• Non-root user access in Docker.

docker exec Command Syntax

The basic syntax for the docker exec command specifies the target container, the command to run, and any arguments for that command:

docker exec [options] [container-name-or-id] [command] [arguments]

The command executed through docker exec:

• Runs while the container's primary process (PID 1) is active.
• Does not restart together with the container.
• Executes in the container's default working directory.
• Must be an executable, not a chained or quoted command.

docker exec Command Options

The docker exec options allow the user to control the execution environment and behavior of a command run inside a container. The table below describes the available docker exec options:

When to Use docker exec Command?

The docker exec command is used when direct interaction with a live container is necessary. The following are the most common scenarios for docker exec:

• Debugging. Inspecting container logs, checking the status of running processes, or modifying configuration files to diagnose and resolve issues.
• Administration. Performing routine operational tasks such as initiating database backups or restarting specific application services within a container.
• Testing. Running test scripts or validating application behavior directly within the isolated environment of a container.
• Interactive shell access. Obtaining a shell prompt inside a container for direct manual operations and exploration.
• Monitoring. Running commands to retrieve performance metrics or verify the operational status of containerized applications.

docker exec Examples

The examples below illustrate common uses of the docker exec command:

• List the detailed contents of the /etc/nginx directory inside the container named exec_test:

docker exec exec_test ls -l /etc/nginx

• Create an interactive psql session as admin_user within my_database_server to allow database commands to be executed:

docker exec -it test_database_server psql -U admin_user

The psql shell prompt appears.

• Execute the find command to locate log files as the user with UID 1001 within the /var/log directory in the exec_test container.

docker exec -u 1001 exec_test find /var/log -name "*.log" -type f

• Run the /app/run_diagnostic.sh script inside my_service_container with the DEBUG_MODE environment variable set to true.

docker exec -e DEBUG_MODE=true test_service_container /app/run_diagnostic.sh

docker exec Best Practices

Adhering to docker exec best practices enhances container management efficiency, improves security, and mitigates potential risks. Implement the following guidelines to ensure secure and reliable container operations:

• Prioritize container health checks. Rely on Docker's built-in health check mechanisms for automated status monitoring instead of manual docker exec calls for basic health validation.
• Avoid persistent changes. Do not use docker exec to make permanent modifications to container configurations or data. Instead, include these modifications in the container image or manage them through mounted volumes.
• Use appropriate shells for interactive sessions. For interactive shell access, prefer well-known shells like bash or sh as they offer a familiar and feature-rich command-line environment.
• Specify the user when necessary. When executing commands that require elevated or specific user permissions, use the --user option to control the command's privileges within the container.
• Limit interactive session duration. Minimize the time spent in interactive docker exec sessions to reduce the potential for security vulnerabilities or accidental misconfiguration.

docker exec Common Pitfalls

Understanding common challenges with docker exec helps troubleshoot and prevent issues. The following are typical scenarios that can lead to unexpected behavior or command failures:

• Container not running. Attempting to execute docker exec on a container that is not running results in an error, as the command requires an active process environment.
• Incorrect container identifier. Using an invalid container name or ID prevents the command from locating the target container, leading to execution failure.
• Missing necessary executables. The command specified for execution must exist within the container's file system and be accessible via its PATH environment variable.
• Permissions issues. The user executing the command inside the container may lack the necessary file system or process permissions for the requested operation, resulting in permission-denied errors.
• Unexpected environment. Commands run via docker exec inherit the container's isolated environment, which may differ significantly from the host system's environment variables or configurations, potentially causing unexpected behavior.

Conclusion

This article explained the function and syntax of the docker exec command. Furthermore, it provided usage examples and offered advice on how to use the command efficiently and securely.

Next, read about alternative ways to access the container shell in How to SSH into a Docker Container.