ENV Instruction Reference

Set environment variables in the container

Syntax

ENV <key>=<value> ... (one or more key-value pairs)
ENV <key> <value> (single key-value pair)

The ENV instruction sets environment variables that will be available to containers created from the image. These environment variables persist when a container is run from the image.

The ENV instruction is used to set environment variables in your Docker image. These variables are available to processes running inside the container, making them a convenient way to configure your application's behavior.

Environment variables set with ENV persist when a container is run from the image, and they can be viewed with docker inspect. They can also be overridden at runtime using the -e or --env flag with docker run.

Forms of the ENV Instruction

The ENV instruction can be used in two forms:

Multiple Key-Value Pairs

Sets multiple environment variables at once:

ENV KEY1=value1 KEY2=value2 KEY3=value3

This is the preferred form as it creates a single layer in the image. Each variable is separated by a space, and values containing spaces must be quoted:

ENV MY_NAME="John Doe" MY_DOG=Rex\ The\ Dog \
    MY_CAT=fluffy
Single Key-Value Pair

Sets a single environment variable:

ENV MY_VAR my-value

In this format, the entire string after the key is treated as the value, including spaces and without requiring quotes:

ENV MY_NAME John Doe

This form is simpler for single variables but creates a new layer for each ENV instruction.

Description

The ENV instruction sets environment variables that will be available to all processes running inside the container. Environment variables are a key mechanism for configuring applications in containerized environments.

Environment variables set with ENV are persistent and become part of the image. They are available during the build process after the point they are set, and are also available to containers created from the final image.

These variables can be used:

  • In subsequent Dockerfile instructions that support environment variable substitution
  • By processes running inside the container
  • By applications that read environment variables for configuration

Environment variables defined with ENV can be referenced in the shell form of other instructions using the standard Unix syntax ($variable_name or ${variable_name}):

ENV APP_HOME /app
WORKDIR $APP_HOME

To use an environment variable in the exec form of instructions (like RUN, CMD, or ENTRYPOINT), you need to execute a shell explicitly:

ENV NAME="World"
RUN ["/bin/bash", "-c", "echo Hello, $NAME"]

Environment variables set with ENV can be overridden at container runtime with the -e flag:

docker run -e "NAME=Docker" myimage

Examples

Basic Usage

Setting basic environment variables:

FROM ubuntu:20.04
ENV DEBIAN_FRONTEND=noninteractive \
    TZ=UTC \
    PATH=/app/bin:$PATH

This sets multiple environment variables in a single instruction, creating only one layer.

Application Configuration

Using environment variables for application configuration:

FROM node:18-alpine
ENV NODE_ENV=production \
    PORT=3000 \
    LOG_LEVEL=info

This configures a Node.js application with production settings.

Using Variables in Instructions

Referencing environment variables in other instructions:

FROM python:3.9-slim
ENV APP_HOME=/app \
    PYTHONUNBUFFERED=1
WORKDIR $APP_HOME
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

This uses an environment variable to set the working directory.

Complex Values

Setting environment variables with complex values:

FROM ubuntu:20.04
ENV DATABASE_URL="postgres://user:password@localhost:5432/db?sslmode=disable" \
    ALLOWED_HOSTS="localhost,example.com,*.example.org" \
    MESSAGE="Hello, Docker world!"

This demonstrates setting variables with spaces, special characters, and quoted values.

Path Manipulation

Using ENV to manipulate the PATH variable:

FROM ubuntu:20.04
ENV PATH="/app/bin:${PATH}" \
    LD_LIBRARY_PATH="/usr/local/lib:${LD_LIBRARY_PATH}"

This prepends custom directories to the PATH and LD_LIBRARY_PATH variables.

Proxy Configuration

Setting proxy environment variables:

FROM alpine:3.14
ENV HTTP_PROXY="http://proxy.example.com:8080" \
    HTTPS_PROXY="http://proxy.example.com:8080" \
    NO_PROXY="localhost,127.0.0.1"

This configures proxy settings for network connections from within the container.

Best Practices

  • Group related variables: Use a single ENV instruction to set multiple related environment variables to reduce image layers.
  • Use for configuration: Use environment variables for application configuration that might change between environments.
  • Consider security: Don't store sensitive information like passwords and API keys in environment variables in the Dockerfile. Use runtime environment variables or secrets management solutions instead.
  • Set defaults: Provide reasonable default values that can be overridden at runtime.
  • Document environment variables: Document the environment variables that your image expects, especially if they're required for proper operation.
  • Consider ARG for build-time variables: For values only needed during build, use ARG instead of ENV to avoid persisting them in the final image.
  • Don't overuse: Don't use environment variables for values that should be hard-coded or for large amounts of data.
  • Clear temporary variables: If you set environment variables for temporary use during build, consider unsetting them in the same layer to avoid persisting them.

ENV vs ARG

It's important to understand the difference between ENV and ARG instructions:

ENV ARG
Available at both build time and runtime Only available at build time
Persists in the final image Does not persist in the final image
Can be overridden at container runtime with -e Can be set at build time with --build-arg
Used for runtime configuration Used for build-time customization

If you need a value only during the build process, use ARG. If you need a value to be available to the running container, use ENV.

You can combine ARG and ENV to create build-time configurable runtime environments:

ARG NODE_ENV=production
ENV NODE_ENV=$NODE_ENV

This allows you to set NODE_ENV at build time with --build-arg, while still making it available at runtime as an environment variable.

Notes and Limitations

  • Environment variables are stored as strings, not as their native data types.
  • Environment variables set with ENV are visible in the Docker image history, so avoid storing sensitive data this way.
  • Each ENV instruction that uses the single key-value pair form creates a new layer in the image. Use the multiple key-value pairs form to minimize layers.
  • Environment variables defined in a Dockerfile can be overridden at runtime using the -e or --env flag with docker run.
  • In shell form instructions (like RUN, CMD, or ENTRYPOINT in shell form), you can reference environment variables directly using $variable_name or ${variable_name}.
  • In exec form instructions (JSON array format), environment variable substitution doesn't happen automatically. You need to use a shell explicitly if you want to use environment variables.
  • The order of ENV instructions matters, as variables can reference previously defined variables but not those defined later in the Dockerfile.

Related Instructions

ARG

Defines build-time variables that can be used in FROM, RUN, and other instructions.

RUN

Executes commands that can use environment variables set with ENV.

CMD

Specifies the default command, which can reference environment variables.

ENTRYPOINT

Configures the container to run as an executable, which can use environment variables.
ENTRYPOINT Instruction
Reference Index

On This Page

Try Our Optimizer

Analyze your Dockerfile for optimization opportunities.

Dockerfile Optimizer

Related Tutorials