How to configure Claude Code to use virtual environments
Run Claude Code commands through uv or the project’s explicit interpreter path. Both select the virtual environment without depending on shell activation.
An activation command in one Bash tool call does not change the environment of later calls. Claude Code can carry the working directory between commands, but environment variables do not persist that way. Activating an environment before launching Claude Code does make it part of the inherited environment.
Use uv for a uv project
Add these commands to the project’s CLAUDE.md:
## Python environment
Use uv for this project's Python commands:
- Run a script: `uv run python script.py`
- Run tests: `uv run pytest`
- Run a Python module: `uv run python -m module_name`
- Add dependencies: `uv add <package>`
Do not activate .venv between tool calls. uv selects it for each command.uv run executes the command inside the project’s virtual environment, ensuring all dependencies are installed first. See configure Claude Code to use uv for scoped approval rules.
Select the interpreter in other projects
For a venv project without uv, put the platform’s interpreter path in CLAUDE.md. Assume the environment already exists at .venv in the project root.
## Python environment
Run commands from the repository root with the project's interpreter:
- Run a script: `.venv/bin/python script.py`
- Install a package: `.venv/bin/python -m pip install <package>`
- Run tests: `.venv/bin/python -m pytest`Use the project’s own installation workflow for dependency changes. The pip examples apply to pip-managed environments; a uv project should use uv add so metadata and its lockfile stay synchronized.
Verify the environment Claude actually uses
Ask Claude to run the matching diagnostic from the repository root:
| Project | Command |
|---|---|
| uv | uv run python -c "import sys; print(sys.executable); print(sys.prefix)" |
| venv on macOS/Linux | .venv/bin/python -c "import sys; print(sys.executable); print(sys.prefix)" |
| venv on Windows | .venv\Scripts\python.exe -c "import sys; print(sys.executable); print(sys.prefix)" |
Both paths should point into the project’s .venv directory. A system or unrelated environment path means the wrong interpreter ran. Check the actual command before adding more configuration.
For cloud or other remote sessions, create and sync the environment on that host too. Local .venv paths and user settings do not provision another machine. Prefer explicit commands over committing machine-specific PATH values.