denver

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

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

What problem does this solve?

Every project needs some setup before it builds — a fresh clone, a submodule init, a venv, a toolchain install. How much varies wildly, but the pattern is the same: you run a pile of one-off steps to get a working build the first time.

denver gives you a declarative way to setup your environment. You describe the steps a project needs in a denver.toml, and denver runs them -- the same way every time on any machine — for you, for teammates, and in CI. denver is optimized to run only necessary stages, so it stays fast.

Documentation

You can find the full documentation in Markdown here

Additionally it is hosted on GitHub Pages.

Install

You can install denver with pip:

pip install denver-tool

If you prefer, you can also install with uv. Please refer to official uv documentation https://docs.astral.sh/uv/getting-started/installation how to install uv

uv tool install denver-tool

Instead of installing denver, you can also run the script src/denver.py directly:

src/denver.py --version

For easier usage you can also set up an alias so it behaves like an installed command:

alias denver="$PWD/src/denver.py"
denver --version

Note: stuck on Python < 3.11 (missing tomllib)? You have to run the script with uv run src/denver.py, e.g by setting alias denver="uv run $PWD/src/denver.py". Alternatively grab a prebuilt executable from a release, or build one yourself with uv run poe pyinstaller.

For more details about how to install or run denver see Install denver →.

Tab Completion

Tab completion works in bash, zsh, and fish.

bash/zsh:

eval "$(denver complete)"

fish:

denver complete | source

For more details see Shell completion →.

Try it out

Have a look at the examples/simple-env/denver.toml:

stages = [
  "print-vars-before",
  "set-vars",
  "print-vars-after",
]

[print-vars-before]
provider = "custom"
cmd = 'echo "[print-vars-before] MYVAR=$MYVAR FOO=$FOO BAR=$BAR"'

[set-vars]
provider = "custom"
cmd = 'echo "[set-vars] sourcing custom.sh..."'
source = "custom.sh"

[print-vars-after]
provider = "custom"
cmd = 'echo "[print-vars-after] MYVAR=$MYVAR FOO=$FOO BAR=$BAR"'

As you can see, this environment consists of three stages.

• First stage prints out the variables and their values how they are currently set (most probably empty)
• Second stage prints some text, and it sources custom.sh script. In this script each variable is set to a value
• Third stage prints out the variables and their values again so see if the second stage has worked

You can run an own command (e.g. printenv FOO MYVAR BAR) within this environment as following:

denver run examples/simple-env -- printenv MYVAR

Output:

[print-vars-before] MYVAR= FOO= BAR=
[set-vars] sourcing custom.sh...
[print-vars-after] MYVAR=1 FOO=2 BAR=3
2
1
3

For available flag (e.g. the -q, see CLI arguments → or run denver --help respectively denver run --help.

You want to see some more advanced example? Have a look at denver in 5 minutes →.

You want to see some even more advanced example? Have a look at denver in 30 minutes →

Known limitations

denver has zero runtime dependencies. Its config format is TOML (denver.toml), parsed with the standard library's tomllib — hence it requires python >=3.11. You are stuck on Python < 3.11 (e.g. Ubuntu 22)? Have a look at install or run denver.

Contributing

Bug reports, feature requests and pull requests are very welcome — see doc/contributing/development.md for the workflow.

To sum up: uv run poe all should always pass.

License

Apache License 2.0 — see LICENSE.