Environments

boks can build custom container images with packages pre-installed, cache them by content hash, and run your tool inside them. This gives you a reproducible, isolated environment for every project without polluting your system.

Inline packages

Append :package1,package2 to install packages into the container before running:

boks python@3.12:requests,jinja2 -c "import requests; print(requests.__version__)"
boks node@18:lodash -e "const _ = require('lodash'); console.log(_.VERSION)"

boks builds a new image layered on top of the base image, caches it by a hash of the base image and package list, and uses the cache on subsequent runs.

Environment files

Use -e @provider:file to load dependencies from a file — the provider is always named explicitly:

boks -e @pip:requirements.txt python script.py
boks -e @npm:package.json node app.js

boks installs dependencies using the named package manager and runs your command.

Auto-detection

Omit the filename (keep the provider) to let boks find the right file in your current directory:

boks -e @pip python script.py      # finds requirements.txt
boks -e @npm node app.js           # finds package.json

Shebang scripts

boks works in shebangs for portable, self-contained scripts:

#!/usr/bin/env -S boks python@3.12:requests,jinja2

import requests
from jinja2 import Template
print(Template("{{ v }}").render(v=requests.__version__))

chmod +x script.py
./script.py

Anyone with boks installed can run the script — no virtualenv setup, no pip install.

Caching

Environments are identified by a hash of the base image reference and package list. The first run builds and caches the image; all subsequent runs with the same inputs start from cache and are near-instant.

Remove all cached environment images:

boks --clean

Language support

Python — pip, uv
Node.js — npm, yarn
R — renv
Ruby — gem (see Package managers)
PHP — composer (see Package managers)
Elixir — hex (see Package managers)
Lua — luarocks (see Package managers)
Ansible — galaxy (collections; see Package managers)
Package managers — provider reference