koopa-python

---
name: koopa-python
description: >-
  Python virtual environment lessons, why moving a project directory breaks
  .venv/bin/activate's hardcoded absolute path, and why direnv's PATH_add is
  relocation-proof where source activate is not. Use when a console-script
  entry point becomes "command not found" after moving a project directory,
  when writing or debugging a .envrc that activates a Python venv, or when
  deciding between PATH_add and source activate under direnv's strict_env.
---

# Python Virtual Environment Lessons

## Moving a `.venv` breaks `activate` scripts: use `PATH_add` in `.envrc` instead

**Symptom.** After moving a project directory, `mycli` (or any console-script
entry point) is `command not found` in a fresh shell, and the shell prompt shows
the wrong Python version (e.g. koopa's system Python instead of the venv's).

**Root cause.** Python `venv` `activate` scripts hardcode the absolute path of
the venv at creation time:

```bash
# .venv/bin/activate (generated by `python -m venv` or `uv venv`)
VIRTUAL_ENV='/old/absolute/path/to/.venv'   # ← NEVER updated on move
```

When the project directory is moved (e.g. `~/git/foo` → `~/git/work/foo`), `uv
sync` regenerates entry-point scripts and `.pth` files at the new path, but does
**not** rewrite the `activate` scripts. If `.envrc` does `source
.venv/bin/activate`, the old (now dead) path is prepended to `PATH`. The real
`.venv/bin` never appears on `PATH` → entry points are not found.

**Fix: use direnv-native `PATH_add` instead of `source activate`.** `PATH_add`
resolves relative to `$PWD`, so it is relocation-proof by design.

```bash
# .envrc: CORRECT (relocation-proof)
if [[ -d '.venv/bin' ]]
then
    export VIRTUAL_ENV="$(expand_path .venv)"
    export VIRTUAL_ENV_PROMPT='.venv'
    PATH_add '.venv/bin'
fi
```

```bash
# .envrc: BROKEN on directory move
if [[ -f '.venv/bin/activate' ]]
then
    source '.venv/bin/activate'   # hardcodes absolute path from creation time
fi
```

`expand_path .venv` is a direnv built-in that turns a relative path into an
absolute one anchored at `$PWD`, it does NOT bake in a hardcoded path.

**Note on `strict_env`.** `source .venv/bin/activate` also interacts poorly
with `strict_env = true` in `direnv.toml` (`set -euo pipefail`). `PATH_add`
is safe under strict mode.

**If you need to fix a stale venv's activate scripts** (for manual `source`
outside direnv), recreate the venv:

```bash
rm -rf .venv && uv sync --extra cli
```

Run this yourself, the agent should NOT run it (no-install rule).