denver

Development Environments as code — reproducible, flexible, simple and fast.

Development Environment Launcher — declares dev environments in a denver.yml: reproducible and layerable to fit your project's needs.

What problem does this solve?

Every project needs some setup before you can build it — and how much varies enormously. A setup.sh is only a suggestion nobody re-runs after a git pull; whatever happens to already be installed on your machine quietly covers for the steps that were never written down. denver declares that setup instead, in a denver.yml, and runs it the same way every time — anywhere from a one-stage script replacement to a five-stage cross-compile toolchain relocated into a container. You only pay for the stages your project actually needs — nothing here is mandatory, and denver has no opinion about which tools you use.

Read the full walkthrough → — the problem built up one step at a time, from that first script to import:-based inheritance across a whole fleet of projects.

Documentation

The built site (search, sidebar nav, one page per topic — and a plain-Markdown mirror of every page under /markdown/ for AI tools/LLMs) is published from doc/ by .github/workflows/docs.yml. Browsing on GitHub instead:

Install

pip install denver-tool   # or: uv tool install denver-tool

Also available: a standalone executable that needs no Python at all, an editable install for hacking on denver itself, and vendoring straight into your own monorepo via git-nested — see Install denver →.

Try it

denver examples/howto-env -- pytest examples/howto-env/tests

A minute or two later (much less on repeat runs) that command has built a container, a Python venv, a hand-installed tool, a conan-installed toolchain and a team convention — and run tests proving all five actually work — from that one denver.yml, on your machine or your colleague's, identically. See Denver in 5 minutes → for the full walkthrough (pre-conditions, what each stage does, the flags you'll actually use), or CLI arguments → / denver --help for every flag.

Known limitations

Every place denver runs needs import yaml to work. denver is a Python program with exactly one runtime dependency, PyYAML, so installing it from PyPI covers the host automatically. What it cannot cover is a wrapped environment: a docker stage relocates the rest of the stack into the container and re-invokes denver in there with the image's own bare python3 — an interpreter that knows nothing about the install on your host. That image must supply PyYAML itself:

RUN apt-get update && apt-get install -y --no-install-recommends \
      python3 python3-yaml \
    && rm -rf /var/lib/apt/lists/*

If it doesn't, denver stops with an error naming the interpreter that failed to import yaml.

Which PyYAML that is, is deliberately not pinned. The host copy and the image copy are resolved by two different package managers and will drift apart in general. denver accepts that: it calls exactly two functions from the library, yaml.safe_load and yaml.safe_dump, whose behaviour has been stable across PyYAML releases for years. So any reasonably recent PyYAML is fine, and denver imports whatever it finds instead of demanding a particular version and forcing every image to track it. The declared dependency is a floor (pyyaml>=6), not a pin — and it constrains only the host install anyway, never the image's.

Contributing

Bug reports, feature requests and pull requests are welcome — see doc/contributing/development.md for the workflow (uv run poe all runs lint, format, mypy and the test suite; denver keeps 100% coverage).

License

Apache License 2.0 — see LICENSE.