---
name: docker-dsl
description: >
  Imperative context-manager DSL for authoring multi-stage Dockerfiles. Use when writing Python code that uses the docker_dsl package.
license: MIT
compatibility: Requires Python >=3.13.
---

# docker-dsl

Imperative context-manager DSL for authoring multi-stage Dockerfiles.

## Installation

```bash
pip install docker-dsl
```

## API overview

### Entry points

Declare config and render a recipe into a Dockerfile.

- `Dockerfile`: Renders a recipe module into Dockerfile text
- `BuildContext`: Recipe-facing handle for config fields, exported as `context`
- `rendering`: Report whether a render pass is in progress

### Stage authoring

Declare stages and emit instructions.

- `Stage`: A build stage — one `FROM` and the instructions that follow it
- `MountScope`: A `with` block that applies a mount to the `RUN` commands inside it
- `EnvScope`: A `with` block that confines env variables to the `RUN` commands inside

### The run builder

Accumulate shell commands into one RUN instruction.

- `RunBuilder`: Accumulates shell commands into a single `RUN` instruction
- `AptMixin`: AptMixin(*, apt_updated: 'bool' = False, apt_dirty: 'bool' = True)
- `RedirectableCmd`: A pending `echo` awaiting a redirect target
- `CdScope`: A `cd` that optionally restores the previous directory
- `CmdInvoker`: A bound shell binary, produced by `RunBuilder`'s attribute dispatch

### Introspection

Query the active build during a render pass.

- `current_stage`: Return the stage of the innermost open `with Stage(...)` block

## Resources

- [Full documentation](https://yasyf.github.io/docker-dsl/)
- [llms.txt](llms.txt) — Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs
- [Source code](https://github.com/yasyf/docker-dsl)