Prerequisites¶

Before using devenv, ensure you have the following tools installed.

Required Tools¶

1. Python 3.12+¶

devenv generates Python 3.12+ projects by default.

macOS (Homebrew)Ubuntu/DebianWindows

brew install python@3.12

sudo apt update
sudo apt install python3.12 python3.12-venv

Download from python.org

2. Cookiecutter¶

The template engine that generates your project.

pip install cookiecutter
# or
pipx install cookiecutter

3. uv (Recommended)¶

Fast, reliable Python package manager used in generated projects.

macOS/LinuxWindowspipx

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

pipx install uv

4. Docker (Optional but Recommended)¶

Required for Dev Containers and containerized development.

macOSLinuxWindows

brew install --cask docker

Follow Docker's official installation guide

Download Docker Desktop

5. just (Optional)¶

A command runner used in generated projects. Not required but recommended.

macOSLinuxWindows

brew install just

curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin

winget install Casey.Just

Optional Tools¶

VS Code¶

For the best Dev Container experience:

Git¶

For version control (you probably already have this):

git --version

Verify Installation¶

Run these commands to verify everything is installed:

# Python
python3 --version  # Should be 3.12+

# Cookiecutter
cookiecutter --version

# uv
uv --version

# Docker (optional)
docker --version

# just (optional)
just --version

Troubleshooting¶

Python not found¶

Ensure Python is in your PATH:

which python3
# or on Windows
where python

Cookiecutter fails to install¶

Try using pipx for isolated installation:

pip install pipx
pipx install cookiecutter

Docker permission denied¶

Add your user to the docker group (Linux):

sudo usermod -aG docker $USER
# Log out and back in

Next Steps¶

Once prerequisites are installed, proceed to:

Quickstart