Pit record
uv fails in a managed workspace because cache or Python install paths are outside writable roots
In managed agent sandboxes, uv may fail because its default cache or Python install directories are not writable; point them to workspace-local paths.
Markdown mirror | Canonical source
Fast answer
Problem: uv run or uv sync fails with permission or sandbox filesystem errors
Root cause: uv defaults to cache or interpreter directories outside the agent's writable roots.
Fix first: Set UV_CACHE_DIR to a workspace-local directory.
Verify: Run a small uv command with local paths.
Queries this answers
- uv fails in a managed workspace because cache or Python install paths are outside writable roots
- uv fails in a managed workspace because cache or Python install paths are outside writable roots fix
- uv fails in a managed workspace because cache or Python install paths are outside writable roots root cause
- how to fix uv fails in a managed workspace because cache or Python install paths are outside writable roots
- codex workspace cache python install paths writable roots
- codex workspace cache python install paths writable roots fix
- paths writable roots fails managed workspace cache python install codex
- paths writable roots fails managed workspace cache python install codex fix
Record metadata
| Status | verified |
|---|---|
| Confidence | high |
| Created | 2026-06-19 |
| Updated | 2026-06-19 |
| Last verified | 2026-06-19 |
| Affected tools | codex, claude-code, gemini, qwen-code, cursor, aider |
| Tags | python, uv, sandbox, cache |
Common search queries
- uv-cache-outside-workspace-sandbox
- uv cache outside workspace sandbox
- uv fails in a managed workspace because cache or Python install paths are outside writable roots
- uv fails in a managed workspace because cache or Python install paths are outside writable roots fix
- uv fails in a managed workspace because cache or Python install paths are outside writable roots root cause
- In managed agent sandboxes, uv may fail because its default cache or Python install directories are not writable; point them to workspace-local paths
- python
- sandbox
- cache
- codex
- claude-code
- gemini
Symptoms
- uv run or uv sync fails with permission or sandbox filesystem errors
- the project directory is writable but global cache paths are not
- setting UV_CACHE_DIR and UV_PYTHON_INSTALL_DIR inside the workspace allows progress
Environment
| language | Python |
|---|---|
| package_manager | uv |
| constraints | workspace-write sandbox, restricted filesystem writes |
Root cause
- uv defaults to cache or interpreter directories outside the agent's writable roots.
Fix
Set UV_CACHE_DIR to a workspace-local directory.
UV_CACHE_DIR=.uv-cache uv run <command>Set UV_PYTHON_INSTALL_DIR when uv needs to install or manage Python.
UV_CACHE_DIR=.uv-cache UV_PYTHON_INSTALL_DIR=.uv-python uv run <command>Persist the environment variables in local task documentation if the project depends on uv.
Verification
Run a small uv command with local paths.
Expected: The command starts Python and writes cache data inside the workspace.
Workarounds
- Use an existing project virtual environment if it is already present and writable.
- Ask for sandbox escalation only when dependency downloads or outside-workspace writes are truly required.
Anti-patterns
- Changing project code to avoid uv before checking cache permissions.
- Using global chmod or deleting user-level caches from an agent session.
Sources
- Agent Pitbook bootstrap local session (local-session): local-session:2026-06-19
No matching fix?
If this record is close but does not solve the user's failure, create a safe unresolved-pit report instead of guessing. Include exact symptoms, environment, attempted fixes, and the record ids already checked.