How to customize uv's virtual environment location

When working with uv projects, the virtual environment is automatically created in a folder called .venv in your project directory.

your-project/
├── pyproject.toml
├── .venv/          # Virtual environment location
└── src/

You can override this default with a flag or an environment variable.

Using the --active flag

Instead of creating a new environment when running uv commands, you can tell it to use an already-activated virtual environment with the --active flag:

# First, activate your preferred virtual environment
source /path/to/my-env/bin/activate

# Then use uv with the active environment
uv sync --active
uv add --active <dependency-name>

This approach is useful when:

• Working with environments created by other tools (virtualenv, conda, etc.)
• Using shared environments across multiple projects
• Integrating with existing development workflows

Using the UV_PROJECT_ENVIRONMENT environment variable

Setting the UV_PROJECT_ENVIRONMENT environment variable overrides the default environment location.

Option 1: Set Globally on Your System

To change the default location for all uv projects system-wide:

On Unix/macOS:

# Add to ~/.bashrc, ~/.zshrc, etc.
export UV_PROJECT_ENVIRONMENT=".uv-venv"

On Windows:

set UV_PROJECT_ENVIRONMENT=.uv-venv

Avoid .env, the conventional name for a dotenv file. A global export also redirects a plain uv venv run inside a project directory, not just uv sync.

Option 2: Set for a Specific Project

Alternatively, set the variable ephemerally when running uv commands like:

UV_PROJECT_ENVIRONMENT=custom-venv uv sync

With a tool like direnv macOS and Linux users can set project-specific environmental variables that will be activated when you enter a particular directory in your terminal. Using direnv, add export UV_PROJECT_ENVIRONMENT=custom-venv to your .envrc to customize your venv location.

Delete the environment you left behind

Pointing UV_PROJECT_ENVIRONMENT somewhere new leaves the previous environment on disk, with no warning that it is now unused. A project that synced to .venv and then to .uv-venv has both directories. Delete the old one yourself once the new location works.

Understand the mismatch warning

Activating one environment and then running uv against a project that uses another prints a warning rather than honoring the activated one:

$ VIRTUAL_ENV=/tmp/other-venv uv run python -c "print('ok')"
warning: `VIRTUAL_ENV=/tmp/other-venv` does not match the project environment path `.venv` and will be ignored; use `--active` to target the active environment instead

uv uses the project environment and ignores VIRTUAL_ENV. Pass --active when you genuinely want the activated one.

Learn More

• uv: A Complete Guide covers what uv does, how fast it is, the core workflows, and recent releases.
• What is a virtual environment? explains what .venv holds and why uv creates one per project.

• uv Project environment path documentation
• direnv installation directions