Configure uv.toml with link-mode=copy to prevent broken venv symlinks #60

New Issue

kert · 2026-03-21T19:12:14Z

kert commented

2026-03-21 19:12:14 +00:00

Problem

The .venv/bin/python symlink periodically breaks because it points to /root/.local/share/uv/python/... (inaccessible to kert). This happens when any process runs uv as root — the absolute symlink bakes in root's python path.

Root cause

uv defaults to link-mode = "symlink" which creates absolute symlinks from .venv/bin/python → the managed python. If the venv was created by root, the symlink targets root's python cache. The kert user can't follow it.

CI already sets UV_LINK_MODE=copy but the local dev environment doesn't.

Fix

Create uv.toml (project-level uv config) with:

link-mode = "copy"
python-preference = "managed"

This makes uv copy the python binary into .venv/bin/ instead of symlinking it. A copy doesn't break when user context changes.

python-preference = "managed" ensures uv always uses its own managed python (from ~/.local/share/uv/python/) rather than system python, which is more predictable.

Also

Add .venv/ to .gitignore if not already there
Document in README that uv sync --dev is the single setup command

Files

uv.toml (new)
.gitignore (verify)

## Problem The `.venv/bin/python` symlink periodically breaks because it points to `/root/.local/share/uv/python/...` (inaccessible to kert). This happens when any process runs uv as root — the absolute symlink bakes in root's python path. ## Root cause uv defaults to `link-mode = "symlink"` which creates absolute symlinks from `.venv/bin/python` → the managed python. If the venv was created by root, the symlink targets root's python cache. The kert user can't follow it. CI already sets `UV_LINK_MODE=copy` but the local dev environment doesn't. ## Fix Create `uv.toml` (project-level uv config) with: ```toml link-mode = "copy" python-preference = "managed" ``` This makes uv **copy** the python binary into `.venv/bin/` instead of symlinking it. A copy doesn't break when user context changes. `python-preference = "managed"` ensures uv always uses its own managed python (from `~/.local/share/uv/python/`) rather than system python, which is more predictable. ## Also - Add `.venv/` to `.gitignore` if not already there - Document in README that `uv sync --dev` is the single setup command ## Files - `uv.toml` (new) - `.gitignore` (verify)

kert added this to the P12: uv Hygiene — fix venv, build system, python resolution milestone 2026-03-21 19:12:14 +00:00

kert added the config label 2026-03-21 19:12:14 +00:00

kert referenced this issue from a commit

2026-03-21 19:16:25 +00:00

uv hygiene: build-system, uv.toml, version pins, auto-recovery hook

kert referenced this issue

2026-03-21 19:16:44 +00:00

P12: uv hygiene — build-system, link-mode, version pins, auto-recovery #62

kert closed this issue

2026-03-21 19:34:02 +00:00

Sign in to join this conversation.