Prepare for Installing Chap Cli - setting development environment
By the end of this guide, you will know how to use tools like uv (Python) or renv (R) to more easily get code up and running on your machine.
Chap on Windows
Chap Core requires WSL2 (Windows Subsystem for Linux 2) to run on Windows. Install Chap within your WSL2 Ubuntu environment, not on the Windows filesystem, as installing Chap on the WSL2 Ubuntu environment significantly improves performance.
Install and Open WSL2
-
Install WSL2: Follow the official WSL2 installation guide
-
Open the WSL terminal from your Windows Start Menu by searching for "WSL"
-
On first launch, you'll be prompted to create a Unix username and password.
-
Create a projects directory within Ubuntu/WSL2:
- Navigate to your projects folder:
- Within this folder, you will later clone and install chap-core. When referring to the terminal later in this guide, please execute these commands within this folder using WSL2.
What Are Virtual Environments?
A virtual environment is an isolated space where your project's dependencies (packages and libraries) live separately from other projects. Without isolation, installing packages for one project can break another — for example, if Project A needs pandas 1.5 but Project B needs pandas 2.0.
Virtual environments solve this by giving each project its own set of packages.
Why Virtual environments?
| Tool | What it isolates | When to use |
|---|---|---|
| venv | Python packages | Learning, simple Python projects |
| uv | Python packages | Python projects (faster, recommended) |
| renv | R packages | R projects, local development |
| Docker | Everything (OS, language, packages) | Sharing code, deployment, cross-platform work |
uv and renv isolate packages — your project gets its own folder of dependencies. You need one of these depending on whether you use Python or R.
Docker goes further — it isolates the entire environment including the operating system. If code runs in a Docker container on your machine, it runs identically on any other machine. CHAP uses Docker to ensure models work the same everywhere. Docker is optional for local development but required if you want to run or share containerized models.
1. Python Virtual Environments (venv)
Python includes a built-in module called venv for creating virtual environments. Understanding how venv works helps you appreciate what tools like uv automate.
Create a virtual environment
This creates a .venv folder containing a copy of the Python interpreter and a place for installed packages.
Activate the environment
When activated, your terminal prompt changes (usually showing (.venv)) and python points to the virtual environment's interpreter.
Further reading: Python venv documentation
2. Install uv
uv is a fast, modern replacement for venv + pip. It creates virtual environments and manages packages automatically — no need to activate/deactivate manually. We recommend uv for CHAP projects.
Official guide: docs.astral.sh/uv/getting-started/installation
Linux / WSL (Ubuntu/Debian)
Verify
You should see something like uv 0.9.0.