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 a environmental 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 UV_PROJECT_ENVIRONMENT environmental variable

Setting the UV_PROJECT_ENVIRONMENT environmental 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=".env"

On Windows:

set UV_PROJECT_ENVIRONMENT=.env

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.

Learn More

• uv Project environment path documentation
• direnv installation directions