# 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:

```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 `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:
```bash
# Add to ~/.bashrc, ~/.zshrc, etc.
export UV_PROJECT_ENVIRONMENT=".env"
```

On Windows:
```cmd
set UV_PROJECT_ENVIRONMENT=.env
```

### 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.

## Learn More

- [uv: A Complete Guide](https://pydevtools.com/handbook/explanation/uv-complete-guide.md) covers what uv does, how fast it is, the core workflows, and recent releases.
* [uv Project environment path documentation](https://docs.astral.sh/uv/concepts/projects/config/#project-environment-path)
* [direnv installation directions](https://direnv.net/#basic-installation)