The feature belongs to YAML itself, not to Docker — Compose just puts it to very good use.

YAML is the language, Compose is just a reader of it

A docker-compose.yml file is written in YAML, a general-purpose data format used far beyond Docker. Before Compose ever applies its own container-specific logic to that file, a YAML parser first reads the raw text and turns it into structured data. Anchors and aliases are a plain YAML feature, defined by the YAML specification itself, that let one part of a document reference and reuse a block defined somewhere else in the same document — completely independent of what that data will later be used for.

The problem this solves in a real compose file

A typical multi-service application often needs the same settings repeated across several services — the same logging configuration, the same restart policy, the same set of environment variables, or the same resource limits. Written out longhand in every single service block, a ten-line settings group repeated across eight services becomes eighty lines of nearly identical text, and a single needed change means finding and editing all eight copies correctly.

Two related but distinct ideas

It’s worth separating two things that often get mentioned in the same breath: YAML anchors and aliases (a general YAML reuse mechanism) and Compose’s extension fields (a Compose-specific naming convention, using keys that start with x-, for storing custom, reusable configuration blocks that Compose itself deliberately ignores). They’re frequently used together — an extension field is often exactly where an anchor gets defined — but understanding them as two separate tools makes both much easier to reason about.

Three small symbols do almost all of the work.

Why the merge key matters so much in practice

A plain alias substitutes in exactly what the anchor defined — useful, but rigid. Real compose files almost always need a shared base plus a few per-service extras layered on top. The merge key is what allows a service to say, in effect, “start with everything from this shared block, then add these specific extra settings on top,” which is the pattern that actually shows up in nearly every real-world use of anchors in a compose file.

flowchart LR
    A["Anchor Definition
(&name)"] -->|"referenced by"| B["Alias
(*name)"]
    A -->|"blended via"| C["Merge Key
(<<: *name)"]
    C --> D["Final Merged Block
(shared settings + local additions)"]
    B --> E["Final Substituted Block
(exact copy of anchor)"]
        

By the time Compose’s own logic runs, anchors are already long gone.

It helps enormously to understand that this entire process happens in two clearly separated stages, handled by two entirely different pieces of software. First, a general-purpose YAML parser reads the raw file and resolves every anchor, alias, and merge key according to the plain YAML specification, producing one fully expanded, anchor-free, in-memory data structure. Only after that is complete does Compose’s own logic run, and by that point, Compose has no awareness that anchors or aliases were ever used at all — it simply sees a normal, fully resolved configuration.

This separation explains why extension fields and anchors combine so naturally: Compose simply ignores any top-level key it doesn’t recognize as a real Compose setting, and keys starting with x- are explicitly guaranteed to always fall into that ignored category. That makes them a safe, stable place to define anchors meant purely for reuse, without Compose ever mistaking them for an actual service or configuration setting of their own.

A deliberately reserved space in the file for content Compose promises never to interpret.

Why a dedicated convention exists at all

Anchors could technically be defined anywhere in a YAML file, including directly inside a real service definition. But placing shared, reusable content inside an actual service block is confusing to read and risks Compose mistaking part of it for a real setting on that service. Compose’s specification solves this by formally reserving any top-level key beginning with x- as an extension field — content Compose will always parse structurally, but will never treat as a real setting, no matter what it contains.

What people typically put in an extension field

The most common use is exactly what this tutorial has been building toward: defining an anchor inside an extension field, purely so it can be referenced and merged into multiple real service definitions elsewhere in the same file. Teams commonly create extension fields for shared logging configuration, common environment variable sets, standard resource limits, or repeated health-check settings.

From a single definition to several fully-formed service configurations.

sequenceDiagram
    participant File as compose.yml
    participant Parser as YAML Parser
    participant Compose as Compose Engine
    participant Services as Running Services

    File->>Parser: Read x-common block with anchor
    File->>Parser: Read service A with merge key reference
    File->>Parser: Read service B with merge key reference
    Parser->>Parser: Resolve anchor content
    Parser->>Parser: Merge into service A
    Parser->>Parser: Merge into service B
    Parser->>Compose: Fully resolved, anchor-free structure
    Compose->>Compose: Ignore x-common (extension field)
    Compose->>Compose: Validate services A and B
    Compose->>Services: Apply final merged configuration
        

What changes if the shared block is edited

Because resolution happens fresh every time the file is parsed, editing the anchor’s content inside the extension field and re-running Compose automatically applies that change to every service that merges it in — with no need to find and update each service individually. This is the entire practical benefit of the pattern: one edit, propagated everywhere it’s referenced, the next time the file is read.

What doesn’t change: per-service overrides

A service that merges in a shared block can still define its own additional keys alongside the merged content, and — depending on how the merge is structured — can override specific values from the shared block for just that one service, keeping the convenience of reuse without losing the flexibility to handle genuine per-service differences.

Compose actually offers more than one way to avoid repetition — and they solve different problems.

Beyond YAML anchors, Compose also has its own dedicated extends keyword, which lets one service definition explicitly inherit settings from another service definition, even one defined in a completely separate file. It’s easy to assume this does the same job as anchors, but the two mechanisms work at different levels and are suited to different situations.

In practice, many teams use both: anchors and extension fields for small, shared settings fragments scattered across several services, and extends for genuinely inheriting from a more complete, related service definition.

Powerful for reducing duplication, but readability has to be actively protected.

This is configuration tooling, not a runtime security boundary — but it still has real security implications.

Propagating a single mistake everywhere at once

The same property that makes shared anchors useful — one change affecting every service that references it — cuts the other way too. A shared block that accidentally includes an overly permissive setting, an unintended exposed port, or a hardcoded secret gets propagated into every single service that merges it in, multiplying a single mistake instead of containing it to one place.

Secrets don’t belong in shared, reused blocks

Sensitive values — passwords, API keys, tokens — should never be placed directly inside an anchor meant for wide reuse, since doing so both spreads that secret across every referencing service and makes the compose file itself a single, high-value target if it ever leaks or gets committed somewhere it shouldn’t. Docker’s own dedicated secrets and environment file mechanisms exist specifically to avoid this pattern.

Because merges happen silently, checking the final result matters more here than in a plain, flat file.

Inspecting the fully resolved configuration

Compose provides a way to output the fully resolved, final configuration exactly as it will actually be used — with every anchor, alias, and merge already expanded — which is by far the most reliable way to confirm that a set of anchors and merges produced the intended result, rather than trying to mentally trace references by eye through the raw file.

The difference between a clean, maintainable file and a confusing one comes down to a few habits.

Pattern: one extension field per logical concern

A clean pattern defines a separate, clearly named extension field for each distinct kind of shared setting — one for logging, one for health checks, one for common environment variables — rather than one enormous catch-all block mixing unrelated settings together, which makes it obvious at a glance what each anchor actually governs.

Pattern: descriptive anchor names

Naming an anchor something specific and descriptive, rather than a generic placeholder, makes every alias reference elsewhere in the file self-explanatory without needing to jump back to the definition to understand what’s actually being pulled in.

Small habits that keep reused configuration genuinely helpful instead of a maintenance headache.

This pattern shows up constantly wherever teams manage several related services in one file.

No. Anchors, aliases, and the merge key are part of the YAML specification itself and work in any YAML file read by a standard-compliant parser, well beyond Docker.

No, an anchor can technically be defined anywhere in the file. Using an extension field is simply the cleanest, officially reserved place to put one, since Compose guarantees it will never try to interpret that content as a real setting.

Not directly — plain YAML anchors only resolve within the single file they’re defined in. Reuse across multiple files is typically handled instead through Compose’s file-combining features or the dedicated “extends” keyword.

The file fails to parse as valid YAML, since an alias without a matching anchor is a structural error the parser catches immediately, well before Compose gets a chance to interpret anything.

Yes. A service can merge in a shared block and also define its own key with the same name directly in its own definition, and depending on ordering, the locally defined value takes precedence — letting most settings come from the shared block while specific ones are overridden per service.

The Compose specification explicitly reserves the “x-” prefix as guaranteed to never be interpreted as a standard setting, precisely so it remains safe for this kind of custom and reusable content indefinitely.

YAML anchors and Docker Compose’s extension fields solve one of the most common everyday frustrations in managing multi-service applications: the same configuration, copy-pasted again and again, quietly drifting out of sync every time only some of the copies get updated. By relying on plain YAML’s own anchor, alias, and merge-key mechanism — resolved entirely before Compose’s own logic ever runs — and by placing shared definitions inside the officially reserved “x-” extension field convention, teams can define a setting once and have it flow consistently into every service that needs it, while still layering on genuine per-service differences exactly where they belong.