# How to customize uv's virtual environment location

When working with [uv](https://pydevtools.com/handbook/reference/uv.md) projects, the [virtual environment](https://pydevtools.com/handbook/explanation/what-is-a-virtual-environment.md) 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:

```bash
# 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](https://pydevtools.com/handbook/reference/virtualenv.md), [conda](https://pydevtools.com/handbook/reference/conda.md), 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:
```bash
# Add to ~/.bashrc, ~/.zshrc, etc.
export UV_PROJECT_ENVIRONMENT=".uv-venv"
```

On Windows:
```cmd
set UV_PROJECT_ENVIRONMENT=.uv-venv
```

Avoid `.env`, the conventional name for a [dotenv file](https://pydevtools.com/handbook/how-to/how-to-manage-environment-variables-in-a-python-project.md). 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:

```bash
UV_PROJECT_ENVIRONMENT=custom-venv uv sync
```

With a tool like [direnv](https://pydevtools.com/handbook/reference/direnv.md) 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:

```console
$ 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.