Let’s build a precise, grounded definition before exploring how Docker specifically uses them.

A simple named value available to a running process

An environment variable is a simple piece of named information — a name paired with a value — made available to a running program by the system it’s running on, rather than being written directly into the program’s own code. A program can check the value of a specific environment variable while it runs, and adjust its own behavior based on whatever it finds.

Older and more general than Docker itself

Environment variables aren’t something Docker invented — they’re a long-standing, general concept in computing, used by all sorts of programs on all sorts of systems to receive small pieces of configuration from whatever’s launching them. Docker simply adopts this same familiar mechanism as one of its primary ways of configuring containers.

This connects directly back to one of the central ideas behind Docker images: build once, run anywhere, unchanged.

The same image, many different situations

As covered in earlier discussions of Docker images, one of the biggest benefits of images is that the exact same, unmodified image can be run in many different contexts — a developer’s laptop, a testing environment, production. But these different contexts often genuinely need different settings: a different database address, a different logging verbosity, different feature toggles.

Avoiding a separate image for every situation

Without a mechanism like environment variables, accommodating these differences would seem to require building an entirely separate image for every single context — a development image, a testing image, a production image — each subtly different, each needing to be separately built and maintained, directly undermining the “build once” benefit images are meant to provide.

Configuration external to the built artifact

Environment variables solve this by keeping configuration entirely separate from the image itself — the image stays exactly the same everywhere, and only the environment variables supplied when a container actually starts differ from one context to another, preserving a single, consistent, well-tested artifact across every environment it runs in.

Contrasting the two approaches directly makes the practical difference concrete.

Baked-in configuration

Baking a specific setting directly into an image — hardcoding a particular database address or a particular mode into the image’s own build process — means that setting becomes permanently fixed for every single container ever started from that exact image, requiring a full rebuild of the image itself to change it for even one deployment.

Environment-variable-based configuration

Supplying that same setting as an environment variable instead means the image itself makes no assumption about what the value should be — the application is simply written to read whatever value it’s given at runtime. The same image can then be started many times, each time with a different value supplied, without ever needing to be rebuilt.

Environment variables can enter a container from several distinct sources — understanding each one matters for predicting the final result.

Defaults baked into the image

An image’s own build process can define default values for specific environment variables, meant to apply automatically unless something later overrides them — useful for settings that have a sensible, common default but might occasionally need to be adjusted.

Values supplied at container start time

Individual environment variables can be explicitly supplied at the moment a container is started, directly specifying a name and value that should apply to that particular container’s run.

Values loaded from a dedicated environment file

Rather than specifying many individual variables one at a time, a whole collection of environment variables can be defined together in a dedicated file, which is then loaded as a group when the container starts — useful for keeping a larger set of related settings organized together.

Values defined within a multi-container application description

For multi-container applications, environment variables for each service can also be defined as part of that service’s own description within the overall application definition, keeping a service’s configuration directly alongside the rest of its definition.

A closer look at what actually happens, mechanically, between “you specify a variable” and “the application can read it.”

Assembling the final set before the process starts

Before a container’s main process actually begins running, Docker gathers every environment variable that applies to it from all the relevant sources described in Chapter 4, resolving any overlaps between them (covered in detail in Chapter 6), and assembles one final, complete set of name-value pairs.

Attaching that set to the process itself

This final, assembled set of environment variables is then attached directly to the container’s main process as it starts, using the same general mechanism any operating system uses to hand environment variables to any program it launches — nothing Docker-specific happens at this level; it’s the same well-established, general-purpose mechanism.

The application reads them like any other program would

From the application’s own point of view, reading these values works exactly as it would for any ordinary program running directly on a regular machine — it simply asks the system for the value associated with a specific variable name, with no awareness needed of where that value ultimately came from.

flowchart LR
    A[Image Defaults] --> D[Final Assembled Set]
    B[Start-Time Values] --> D
    C[Environment File] --> D
    D --> E[Attached to Container's Process]
    E --> F[Application Reads Values Normally]
        

Because multiple sources can potentially define a value for the same variable name, understanding which one actually wins is essential.

Why conflicts can happen

It’s entirely possible for the same variable name to be given a value in more than one place — perhaps a default baked into the image, and also an explicit override supplied at container start. Docker needs a clear, predictable rule for which of these competing values actually takes effect.

The general precedence pattern

In general, values supplied more explicitly and closer to the actual moment a container starts take precedence over more general, earlier-defined defaults. A value explicitly set at container start time will typically override a same-named default baked into the image, since it represents a more specific, deliberate choice made for that particular run.

Why understanding this order matters

Without a clear mental model of this precedence, it’s easy to be confused by a container that doesn’t seem to be picking up an expected value — often because a different source, higher in the precedence order, is quietly overriding what was set elsewhere.

In applications built from several containers working together, environment variables take on some additional, useful patterns.

Per-service configuration, kept alongside each service

As mentioned in Chapter 4, each service within a multi-container application description can define its own specific set of environment variables, keeping that service’s configuration clearly scoped to it, rather than mixed together with every other service’s settings.

Sharing common values across services

Some values genuinely need to be consistent across multiple services at once — for instance, several services all needing to know the same shared address for a common dependency. Careful organization of environment variables (often through a shared environment file referenced by multiple services) helps avoid the same value being defined inconsistently in several different places.

Referencing values defined elsewhere

Multi-container application definitions often support referencing a value defined once, elsewhere, within the environment variable values themselves — letting one central definition be reused across multiple services, reducing the risk of the same conceptual value silently drifting apart if it were instead duplicated by hand in several places.

flowchart TD
    E[Shared Environment File] --> S1[Service A Config]
    E --> S2[Service B Config]
    E --> S3[Service C Config]
        

This is one of the most important practical cautions around environment variables, and deserves careful attention.

The tempting convenience

Because environment variables are such a simple, universally supported way to pass configuration into a container, it’s tempting to use them for absolutely everything a container needs to know — including passwords, API keys, and other genuinely sensitive credentials.

Why this convenience comes with real risk

Environment variables are, by design, relatively easy to inspect — visible through various inspection commands, often captured in logs or error messages if an application isn’t careful, and sometimes even visible to other processes under certain conditions. None of this is a flaw in environment variables themselves; it’s simply a consequence of them being designed for ordinary, non-sensitive configuration, not for securely handling secrets.

Purpose-built alternatives exist for a reason

Dedicated secret-management mechanisms exist specifically to address these gaps, offering more careful handling, more restricted visibility, and better auditability than environment variables were ever designed to provide. Reaching for a purpose-built secrets mechanism, rather than an environment variable, for genuinely sensitive values is a meaningfully safer default.

A subtle but important distinction exists between environment variables used while an image is being built versus those used once a container is actually running.

Build-time values, used only during the build itself

Some values are needed only temporarily, during the image’s own build process — perhaps to select a particular version of something to install, or to configure some aspect of how the build itself proceeds. These values can be supplied specifically for use during the build, without necessarily persisting into the final image or any container started from it.

Run-time values, used by the actual running application

Separately, run-time environment variables are the ones actually read by the application itself while it’s running as a container — the ordinary, everyday use case discussed throughout most of this post.

Why the distinction matters

Confusing these two categories can lead to accidentally leaving build-time-only values (which might include something sensitive, like credentials used solely to fetch a private dependency during the build) unintentionally present in the final image, or conversely, expecting a value only ever supplied at container run time to somehow already be available during the build process, when it was never part of that context at all.

Beyond the specific secrets caution in Chapter 9, environment variables carry a few other security-relevant considerations worth understanding.

Visibility to anyone who can inspect the container

Anyone with sufficient access to inspect a running (or even stopped) container can typically see its environment variables, which means anything genuinely sensitive placed there is effectively visible to that same broad set of people — an important consideration when deciding who should have that level of access in the first place.

Accidental exposure through logs and error output

Applications that log their own startup configuration, or that produce error messages including environment details for debugging purposes, can inadvertently leak sensitive values placed in environment variables into logs — a much wider and harder-to-control exposure path than the variables’ original, intended use.

Environment files deserve careful handling too

A dedicated environment file, especially one containing anything sensitive, needs the same careful handling as any other file holding sensitive material — appropriate access restrictions, careful consideration of whether it should be included in version control, and awareness of who can read it.

Environment variables benefit from some dedicated visibility too, particularly around configuration correctness and drift.

Auditing effective configuration

Periodically reviewing what environment variables a container is actually running with — the final, resolved set after precedence has been applied — helps confirm the running configuration genuinely matches what was intended, especially in setups with several overlapping sources.

Detecting configuration drift across environments

Comparing the environment variables used across different environments (development, testing, production) for the same underlying image helps surface unintended, undocumented differences that might otherwise explain confusing behavioral differences between those environments.

Watching for sensitive values in the wrong places

Scanning logs, error outputs, and environment files for accidentally-exposed sensitive values that should have been handled through a dedicated secrets mechanism instead is a valuable, ongoing security check, not just a one-time review.

Good pattern — externalize genuinely variable settings, keep truly fixed ones baked in

Thoughtfully distinguishing between settings that genuinely differ across environments (good candidates for environment variables) and settings that will realistically never change (reasonable to leave baked into the image) keeps configuration clear and appropriately scoped, rather than externalizing everything indiscriminately.

Good pattern — sensible, safe defaults with explicit overrides

Providing a sensible default value baked into the image for non-sensitive settings, while still allowing that default to be explicitly overridden when needed, offers a convenient “it just works” experience out of the box without sacrificing the flexibility to adjust it for specific contexts.

No, that’s precisely the point — a value supplied at container start time, or through an environment file, can be different every time you start a container from the same, unmodified image.

Docker resolves the conflict using a defined precedence order — generally, a value supplied more explicitly and closer to the actual moment the container starts takes priority over more general, earlier-defined defaults.

Not in the ordinary sense. Environment variables are resolved once, when the container starts, and generally remain fixed for that container’s lifetime — changing a value typically means starting a new container with the updated value.

It’s a common but risky practice. Environment variables are relatively easy to inspect and can end up in logs or error output. A purpose-built secrets mechanism offers meaningfully better protection for genuinely sensitive values like passwords.

A build-time variable is used only while the image is being built, and doesn’t necessarily persist afterward. A run-time variable is read by the actual application once it’s running as a container — the two serve genuinely different purposes and contexts.

Environment variables are what let a single, unchanged Docker image behave correctly across many different contexts — development, testing, production — without needing to be rebuilt for each one. By externalizing configuration that genuinely varies, while leaving truly fixed values baked into the image, they preserve the core “build once, run anywhere” promise that makes images so valuable in the first place. Understanding where environment variables can come from, how precedence resolves conflicts between overlapping sources, how they behave across multi-container applications, and — critically — why they’re a poor fit for genuinely sensitive data, is what allows them to be used well: as a simple, effective configuration mechanism, applied deliberately rather than as a catch-all for absolutely everything a container might need to know.