Python Environments

Inline packages

Append :pkg1,pkg2 to install packages before running:

boks python@3.12:requests,jinja2 -c "import requests; print(requests.__version__)"
boks python@3.11:numpy,pandas script.py

You can pin package versions using standard pip syntax:

boks python@3.12:requests==2.31.0,jinja2>=3.0 script.py

requirements.txt

boks -e @pip:requirements.txt python script.py

boks reads the file, builds a pip-based image, caches it, and runs the script. If the file changes, the image is rebuilt on the next run.

With uv

boks -e @uv:requirements.txt python script.py

uv is a fast Python package installer. Use it by specifying the @uv provider.

Auto-detect

boks -e @pip python script.py   # finds requirements.txt in CWD

pyproject.toml

boks -e @uv:pyproject.toml python script.py
boks -e @uv python script.py    # auto-detects pyproject.toml or requirements.txt

Shebang scripts

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

import requests
from jinja2 import Template

t = Template("Hello, {{ name }}!")
print(t.render(name="world"))

chmod +x script.py
./script.py

The shebang pins both the Python version and the packages. The script runs identically on any machine with boks installed.

Version matrix

Test against multiple Python versions by running the same command with different tags:

boks python@3.11:pytest pytest tests/
boks python@3.12:pytest pytest tests/
boks python@3.13:pytest pytest tests/