Stage authoring

Stage

A build stage — one FROM and the instructions that follow it.

Usage

Stage(
    base,
    name="base",
    graph=current_graph.get(),
    instructions=list(),
    mounts_stack=list(),
    env_stack=list(),
    counter=0
)

Open a stage as a context manager; every method call inside the block appends an instruction to it. Derive child stages with stage and copy artifacts between them with copy.

Parameters

base: str: The base image, or a parent stage’s name for a derived stage.
name: str = "base": The stage name used in FROM ... AS <name>. Child stages created with stage infer this from the as target.

Example

>>> with Stage("ubuntu:24.04") as s:
...     s.workdir("/app")
...     s.cmd("./server")

Methods

Name	Description
arg()	Emit an `ARG` build argument.
env()	Emit an `ENV` instruction, and optionally scope it.
add_to_path()	Prepend entries to `PATH` with an `ENV` instruction.
workdir()	Emit a `WORKDIR` instruction.
copy()	Emit a `COPY` instruction.
entrypoint()	Emit an `ENTRYPOINT` in exec form.
cmd()	Emit a `CMD` in exec form.
run()	Emit a `RUN` instruction, directly or via a builder.
cache()	Scope a BuildKit cache mount over a `with` block.
secret()	Scope a BuildKit secret mount over a `with` block.
bind()	Scope a BuildKit bind mount over a `with` block.
stage()	Derive a child stage from this one (`FROM <this stage> AS ...`).

arg()

Emit an ARG build argument.

Usage

Source

arg(name, value, *, env=False)

Parameters

name: str: Argument name.
value: str: Default value.
env: bool = False: When True, also emit an ENV that forwards the argument into the image environment.

env()

Emit an ENV instruction, and optionally scope it.

Usage

Source

env(mapping)

Keys whose value is None are dropped, so a conditional value need not be guarded at the call site. Used as a plain call, the variables persist for the rest of the stage. Used as a with block, they apply only to the RUN commands inside it (see EnvScope).

Parameters

mapping: dict[str, str] | dict[str, str | None]: Environment variables to set. None values are skipped.

Returns

EnvScope: An EnvScope for optional with-block scoping.

add_to_path()

Prepend entries to PATH with an ENV instruction.

Usage

Source

add_to_path(*entries)

Parameters

*entries: str: Directories to prepend, ahead of the existing $PATH.

workdir()

Emit a WORKDIR instruction.

Usage

Source

workdir(path)

Parameters

path: str: The working directory for later instructions.

copy()

Emit a COPY instruction.

Usage

Source

copy(src, dst=None, *, image=None, stage=None, from_=None, link=None)

Pass stage to copy an artifact from another stage (COPY --from), image to copy from a named image, or neither to copy from the build context. --link is added automatically for cross-stage and cross-image copies; override with link.

Parameters

src: str: Source path.
dst: str | None = None: Destination path. Defaults to src.
image: str | None = None: Image to copy from.
stage: Stage | None = None: Stage to copy from; its name becomes the --from value.
from_: str | None = None: Raw --from value, when neither image nor stage fits.
link: bool | None = None: Force --link on or off.

entrypoint()

Emit an ENTRYPOINT in exec form.

Usage

Source

entrypoint(*cmd)

Parameters

*cmd: str: The executable and its fixed arguments.

cmd()

Emit a CMD in exec form.

Usage

Source

cmd(*args)

Parameters

*args: str: The default command and arguments.

run()

Emit a RUN instruction, directly or via a builder.

Usage

Source

run(self) -> RunBuilder
run(self, args: str = (), env: dict[str, str] | None = None) -> None

Called with arguments, it emits one RUN for that single command. Called with no arguments, it returns a RunBuilder to use as a with block; the commands accumulated inside it become one &&-joined RUN, picking up any mounts and env scopes open around the block.

Parameters

*args: str: A single command’s words. Omit to get a RunBuilder.
env: dict[str, str] | None = None: Inline environment variables for the command.

Returns

RunBuilder | None: A RunBuilder when called with no arguments; otherwise None.

Example

>>> with s.run() as r:
...     r.apt_install("git", "curl")

cache()

Scope a BuildKit cache mount over a with block.

Usage

Source

cache(target, *, lock=False)

Every RUN inside the block mounts a persistent cache at target, so package and build caches survive between builds.

Parameters

target: str: Mount path inside the container.
lock: bool = False: Use sharing=locked instead of the default shared, to serialize concurrent builds that write the same cache.

Returns

MountScope: A MountScope to use as a with block.

secret()

Scope a BuildKit secret mount over a with block.

Usage

Source

secret(secret_id, *, target)

The secret is mounted only for RUN commands inside the block and never lands in an image layer.

Parameters

secret_id: str: Secret id, supplied at build time with docker build --secret.
target: str: Mount path inside the container.

Returns

MountScope: A MountScope to use as a with block.

bind()

Scope a BuildKit bind mount over a with block.

Usage

Source

bind(*, source, target)

Mounts a build-context path read-only for RUN commands inside the block, avoiding a COPY when files are only needed during the command.

Parameters

source: str: Path in the build context.
target: str: Mount path inside the container.

Returns

MountScope: A MountScope to use as a with block.

stage()

Derive a child stage from this one (FROM <this stage> AS ...).

Usage

Source

stage(*, name=None)

The child’s name is taken from the as target of the with statement — with base.stage() as builder: names it builder — so it need not be passed. Override with name.

Parameters

name: str | None = None: Explicit stage name, overriding the inferred one.

Returns

Stage: A new Stage based on this stage.

Example

>>> with base.stage() as builder:
...     builder.run("make")

MountScope

A with block that applies a mount to the RUN commands inside it.

Usage

Source

MountScope(stage, mount)

Returned by Stage.cache, Stage.secret, and Stage.bind. Nest several in one with to apply them together. You rarely construct this directly.

Parameter Attributes

stage: Stage
mount: Mount

EnvScope

A with block that confines env variables to the RUN commands inside.

Usage

Source

EnvScope(stage, env)

Returned by Stage.env. Inside the block, the variables are exported ahead of each RUN rather than emitted as a stage-wide ENV, so they do not leak into the image. You rarely construct this directly.

Parameter Attributes

stage: Stage
env: dict[str, str]