ENTRYPOINT Instruction Reference

Configure a container to run as an executable

Syntax

ENTRYPOINT ["executable", "param1", "param2"] (exec form, preferred)
ENTRYPOINT command param1 param2 (shell form)

The ENTRYPOINT instruction configures a container to run as an executable. Any command-line arguments passed to docker run <image> will be appended to the ENTRYPOINT parameters and will override all elements specified using CMD.

The ENTRYPOINT instruction allows you to configure a container that will run as an executable. It's similar to CMD in that it specifies what command to run when the container starts, but with some important differences in how it handles command-line arguments.

Containers run as executables by default, even without ENTRYPOINT. However, using ENTRYPOINT gives you more control over what happens when your container is run with arguments.

Forms of the ENTRYPOINT Instruction

The ENTRYPOINT instruction can be used in two forms:

Exec Form (Preferred)

The command is run directly, without shell processing:

ENTRYPOINT ["executable", "param1", "param2"]

This is the preferred form for ENTRYPOINT instructions in production Dockerfiles. It's parsed as a JSON array, which means that you must use double-quotes (") around words, not single-quotes (').

Shell Form

The command is run in a shell, which by default is /bin/sh -c on Linux or cmd /S /C on Windows:

ENTRYPOINT command param1 param2

This form processes shell variables, but uses the shell process as PID 1, which doesn't properly pass signals, and makes it harder to handle in container orchestration systems.

Description

The ENTRYPOINT setting in a Dockerfile defines the command that will always be executed when the container starts. Unlike CMD, which can be overridden by command-line arguments, ENTRYPOINT will always run, and command-line arguments are passed to it as additional parameters.

The primary use case for ENTRYPOINT is when you want your container to behave like a binary executable. For example, if you want a container that runs an NGINX server, you would use ENTRYPOINT to specify the nginx executable.

Only the last ENTRYPOINT instruction in the Dockerfile will have an effect. If multiple ENTRYPOINT instructions are specified, only the last one is used.

The ENTRYPOINT instruction can be overridden at runtime using the --entrypoint flag when running a container:

docker run --entrypoint="bash" myimage

Unlike CMD, which is completely replaced by any command-line arguments passed to docker run, with ENTRYPOINT, any command-line arguments are appended as parameters to the ENTRYPOINT. This makes ENTRYPOINT ideal for creating "wrapper" containers that act as if they were the executable itself.

ENTRYPOINT and CMD Interaction

ENTRYPOINT and CMD can work together to provide a flexible container configuration:

  • ENTRYPOINT defines the executable that will run
  • CMD provides default arguments that can be overridden at runtime

If both ENTRYPOINT and CMD are specified in the Dockerfile, CMD's contents are appended as arguments to ENTRYPOINT. For example:

ENTRYPOINT ["nginx"]
CMD ["-g", "daemon off;"]

results in the command: nginx -g daemon off;

If you run the container with additional arguments, they replace the CMD arguments but not the ENTRYPOINT. For example:

docker run myimage -t

results in the command: nginx -t

This pattern allows you to create containers that have a default behavior but can also be used in different ways by passing different arguments at runtime.

Examples

Basic Usage (Exec Form)

Setting the container to run a specific executable:

FROM nginx:alpine
ENTRYPOINT ["nginx", "-g", "daemon off;"]

This ensures the container always runs Nginx in the foreground, regardless of any runtime arguments.

With Default Arguments

Using ENTRYPOINT with CMD for default arguments:

FROM ubuntu:20.04
ENTRYPOINT ["ping"]
CMD ["localhost"]

By default, the container will run "ping localhost", but you can override the destination by providing arguments at runtime.

Creating a Command Wrapper

Creating a wrapper script with ENTRYPOINT:

FROM alpine:3.14
COPY docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.sh
ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["--help"]

This uses a custom script as the entrypoint, which can handle setup tasks before executing the main process.

Shell Form Example

Using environment variables with the shell form:

FROM ubuntu:20.04
ENV GREETING "Hello, Docker!"
ENTRYPOINT echo $GREETING

This will output "Hello, Docker!" with environment variable substitution, but doesn't properly handle signals or parameters.

CLI Tool Container

Making a container act like a CLI tool:

FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY cli.py .
ENTRYPOINT ["python", "cli.py"]

This allows you to pass arguments directly to your Python script as if the container were the script itself.

Database Initialization

Using an entrypoint script for database initialization:

FROM postgres:13
COPY init-db.sh /docker-entrypoint-initdb.d/
ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["postgres"]

The postgres image includes a docker-entrypoint.sh script that runs initialization scripts before starting the database.

Best Practices

  • Use the exec form: Always use the exec form (JSON array format) for ENTRYPOINT instructions to ensure proper signal handling and process control.
  • Combine with CMD: Use ENTRYPOINT together with CMD to create containers with default behavior that can also be customized at runtime.
  • Create entrypoint scripts: For complex initialization logic, use a shell script as your entrypoint to handle setup tasks before launching the main process.
  • Handle signals properly: Ensure your entrypoint properly passes signals to child processes, especially SIGTERM for graceful container shutdown.
  • Consider exec in shell scripts: If your entrypoint is a shell script, use exec to launch the final process so it becomes PID 1.
  • Document your entrypoint: Clearly document what your entrypoint does and what arguments it accepts.
  • Keep it simple: Make your ENTRYPOINT fulfill a single, clear purpose for the container.
  • Test with different arguments: Verify that your container works correctly with various runtime arguments.

Notes and Limitations

  • Only the last ENTRYPOINT instruction in the Dockerfile will take effect.
  • The ENTRYPOINT instruction can be overridden at runtime using the --entrypoint flag.
  • When using shell form, the specified command is executed as an argument to /bin/sh -c on Linux or cmd /S /C on Windows.
  • In shell form, the command runs as a child of the shell, which means it doesn't receive Unix signals (like SIGTERM) and isn't suitable for containers that need to handle graceful shutdown.
  • The exec form is parsed as a JSON array, which means that you must use double-quotes (") around words, not single-quotes (').
  • When using the exec form, normal shell processing doesn't happen. For example, environment variable substitution doesn't work directly in the exec form.
  • If ENTRYPOINT is not specified, Docker will use /bin/sh -c as the default entrypoint for shell form commands.

Related Instructions

CMD

Provides default arguments for the ENTRYPOINT or specifies a command if ENTRYPOINT is not used.

RUN

Executes commands during image build, as opposed to ENTRYPOINT's runtime execution.

ENV

Sets environment variables that can be referenced in the ENTRYPOINT instruction.

COPY

Often used to copy entrypoint scripts into the container.
CMD Instruction
ENV Instruction

On This Page

Try Our Optimizer

Analyze your Dockerfile for optimization opportunities.

Dockerfile Optimizer

Related Tutorials