policyengine/python

Python Environment — PolicyEngine Standard

All PolicyEngine Python work uses uv with Python 3.13 and a local .venv.

Required tools

• uv — fast Python package and project manager
• Python 3.13 (installed/managed via uv)

Install uv if not present:

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

---

Creating a new environment

Always create a .venv at the project root using Python 3.13:

uv venv --python 3.13
source .venv/bin/activate

On Windows:

uv venv --python 3.13
.venv\Scripts\activate

---

Installing packages

Always use uv pip install, never bare pip install:

# Install a package
uv pip install policyengine

# Install from requirements file
uv pip install -r requirements.txt

# Install the current project in editable mode
uv pip install -e .

# Install with extras
uv pip install -e ".[dev]"

Verifying latest package versions

If the user asks for the "latest", "current", or "newest" version of a Python package, verify it from PyPI immediately before installing or pinning it. Do not treat search snippets, local installed versions, lockfiles, stale docs, or repo dependency constraints as proof of latest.

export PACKAGE=policyengine

# Authoritative PyPI metadata.
python - <<'PY'
import json
import os
import urllib.request

package = os.environ["PACKAGE"]
with urllib.request.urlopen(
    f"https://pypi.org/pypi/{package}/json",
    timeout=20,
) as response:
    print(json.load(response)["info"]["version"])
PY

# Cross-check available versions when pip can reach PyPI.
python -m pip index versions "$PACKAGE"

Then install the exact verified version and confirm the resolved distribution:

VERSION=1.2.3
uv pip install "${PACKAGE}==${VERSION}"

python - <<'PY'
from importlib import metadata
import os

package = os.environ["PACKAGE"]
print(f"{package}=={metadata.version(package)}")
direct_url = metadata.distribution(package).read_text("direct_url.json")
if direct_url:
    print(direct_url)
PY

For extras, query the base distribution and pin the extra install to that same version, for example uv pip install "policyengine[us]==4.14.2".

---

Running Python

After activating the venv, run Python normally:

python script.py
python -m pytest

Or run without activating using uv:

uv run python script.py
uv run pytest

---

Checking the environment

# Confirm Python version (should be 3.13.x)
python --version

# Confirm uv is being used
which pip   # should point to .venv
uv pip list

---

Common patterns

New repo setup

uv venv --python 3.13
source .venv/bin/activate
uv pip install -e ".[dev]"

Adding a dependency to pyproject.toml, then syncing

# Edit pyproject.toml to add the dependency, then:
uv pip install -e .

Running tests

uv run pytest
# or after activating:
pytest

---

Resolving venv conflicts

If you see a warning like:

warning: `VIRTUAL_ENV=/Users/.../.venv` does not match the project environment path `.venv` and will be ignored

This means a different venv is active (e.g. a global one at ~/.venv). Fix with:

# Option 1: Deactivate and use uv run
deactivate
uv run python script.py

# Option 2: Use --active flag to force uv to use the active env
uv run --active python script.py

# Option 3: Activate the correct project venv explicitly
source /path/to/project/.venv/bin/activate
python script.py

Do not mix venvs between projects. Each project should have its own .venv at the repo root.

Rules

• Never use python -m venv — always uv venv
• Never use bare pip install — always uv pip install
• Always target Python 3.13 (--python 3.13)
• Always create the venv at the project root as .venv
• Use uv run <cmd> as an alternative to activating the venv manually
• If a venv conflict warning appears, use deactivate then uv run