> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# uv venv

> Create a virtual environment

# uv venv

Create a virtual environment.

## Usage

```bash theme={null}
uv venv [OPTIONS] [PATH]
```

## Description

By default, creates a virtual environment named `.venv` in the working directory. An alternative path may be provided positionally.

If in a project, the default environment name can be changed with the `UV_PROJECT_ENVIRONMENT` environment variable; this only applies when run from the project root directory.

If a virtual environment exists at the target path, it will be removed and a new, empty virtual environment will be created.

When using uv, the virtual environment does not need to be activated. uv will find a virtual environment (named `.venv`) in the working directory or any parent directories.

## Arguments

### `[PATH]`

The path to the virtual environment to create.

Defaults to `.venv` in the working directory.

Relative paths are resolved relative to the working directory.

```bash theme={null}
# Create .venv in current directory
uv venv

# Create virtual environment at specific path
uv venv my-project-env

# Create in specific directory
uv venv /path/to/venv
```

## Options

### Python selection

#### `-p, --python <PYTHON>`

The Python interpreter to use for the virtual environment.

During virtual environment creation, uv will not look for Python interpreters in virtual environments.

See `uv help python` for details on Python discovery and supported request formats.

```bash theme={null}
# Use specific Python version
uv venv --python 3.12

# Use specific Python executable
uv venv --python /usr/bin/python3.11

# Use Python version with specifier
uv venv --python ">=3.11,<3.13"

# Use PyPy
uv venv --python pypy3.10
```

Environment variable: `UV_PYTHON`

### Environment options

#### `--seed`

Install seed packages (`pip`, `setuptools`, and `wheel`) into the virtual environment.

Note that `setuptools` and `wheel` are not included in Python 3.12+ environments.

```bash theme={null}
uv venv --seed
```

This is useful for compatibility with tools that expect these packages to be available.

Environment variable: `UV_VENV_SEED`

#### `--system-site-packages`

Give the virtual environment access to the system site packages directory.

Unlike `pip`, when a virtual environment is created with `--system-site-packages`, uv will not take system site packages into account when running commands like `uv pip list` or `uv pip install`. The `--system-site-packages` flag will provide the virtual environment with access to the system site packages directory at runtime, but will not affect the behavior of uv commands.

```bash theme={null}
uv venv --system-site-packages
```

#### `--prompt <PROMPT>`

Provide an alternative prompt prefix for the virtual environment.

By default, the prompt is dependent on whether a path was provided to `uv venv`:

* If provided (e.g., `uv venv project`), the prompt is set to the directory name
* If not provided (`uv venv`), the prompt is set to the current directory's name

If "." is provided, the current directory name will be used regardless of whether a path was provided to `uv venv`.

```bash theme={null}
# Use custom prompt
uv venv --prompt myproject

# Use current directory name
uv venv my-env --prompt .
```

### Relocatability

#### `--relocatable`

Make the virtual environment relocatable.

A relocatable virtual environment can be moved around and redistributed without invalidating its associated entrypoint and activation scripts.

Note that this can only be guaranteed for standard `console_scripts` and `gui_scripts`. Other scripts may be adjusted if they ship with a generic `#!python[w]` shebang, and binaries are left as-is.

As a result of making the environment relocatable (by way of writing relative, rather than absolute paths), the entrypoints and scripts themselves will not be relocatable. In other words, copying those entrypoints and scripts to a location outside the environment will not work, as they reference paths relative to the environment itself.

```bash theme={null}
uv venv --relocatable
```

#### `--no-relocatable`

Don't make the virtual environment relocatable.

Disables the default relocatable behavior when the `relocatable-envs-default` preview feature is enabled.

```bash theme={null}
uv venv --no-relocatable
```

### Path behavior

#### `--clear`

Remove any existing files or directories at the target path.

By default, `uv venv` will exit with an error if the given path is non-empty. The `--clear` option will instead clear a non-empty path before creating a new virtual environment.

```bash theme={null}
uv venv --clear
```

Environment variable: `UV_VENV_CLEAR`

#### `--allow-existing`

Preserve any existing files or directories at the target path.

By default, `uv venv` will exit with an error if the given path is non-empty. The `--allow-existing` option will instead write to the given path, regardless of its contents, and without clearing it beforehand.

WARNING: This option can lead to unexpected behavior if the existing virtual environment and the newly-created virtual environment are linked to different Python interpreters.

```bash theme={null}
uv venv --allow-existing
```

### Project discovery

#### `--no-project`

Avoid discovering a project or workspace.

By default, uv searches for projects in the current directory or any parent directory to determine the default path of the virtual environment and check for Python version constraints, if any.

```bash theme={null}
uv venv --no-project
```

Alias: `--no-workspace`

### Index options

#### `--index-strategy <INDEX_STRATEGY>`

The strategy to use when resolving against multiple index URLs.

By default, uv will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (`first-index`). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

```bash theme={null}
uv venv --seed --index-strategy unsafe-best-match
```

Values:

* `first-index` - Only use results from the first index that returns a match for a given package name (default)
* `unsafe-best-match` - Search all indexes for the best match
* `unsafe-first-match` - Search all indexes, and use the first match

Environment variable: `UV_INDEX_STRATEGY`

#### `--keyring-provider <KEYRING_PROVIDER>`

Attempt to use `keyring` for authentication for index URLs.

At present, only `--keyring-provider subprocess` is supported, which configures uv to use the `keyring` CLI to handle authentication.

Defaults to `disabled`.

```bash theme={null}
uv venv --seed --keyring-provider subprocess
```

Environment variable: `UV_KEYRING_PROVIDER`

### Package filtering

#### `--exclude-newer <EXCLUDE_NEWER>`

Limit candidate packages to those that were uploaded prior to the given date.

Accepts:

* RFC 3339 timestamps (e.g., `2006-12-02T02:07:43Z`)
* Local dates in the same format (e.g., `2006-12-02`) resolved based on your system's configured time zone
* "Friendly" durations (e.g., `24 hours`, `1 week`, `30 days`)
* ISO 8601 durations (e.g., `PT24H`, `P7D`, `P30D`)

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

```bash theme={null}
uv venv --seed --exclude-newer "2024-01-01"
```

Environment variable: `UV_EXCLUDE_NEWER`

#### `--exclude-newer-package <EXCLUDE_NEWER_PACKAGE>`

Limit candidate packages for a specific package to those that were uploaded prior to the given date.

Accepts package-date pairs in the format `PACKAGE=DATE`, where `DATE` follows the same formats as `--exclude-newer`.

Can be provided multiple times for different packages.

```bash theme={null}
uv venv --seed --exclude-newer-package numpy="2024-01-01" --exclude-newer-package pandas="1 week"
```

### Link mode

#### `--link-mode <LINK_MODE>`

The method to use when installing packages from the global cache.

This option is only used for installing seed packages.

Defaults to `clone` (also known as Copy-on-Write) on macOS and Linux, and `hardlink` on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (`uv cache clean`) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

```bash theme={null}
uv venv --seed --link-mode copy
```

Values:

* `clone` - Clone files (Copy-on-Write) from the cache
* `copy` - Copy files from the cache
* `hardlink` - Hard link files from the cache
* `symlink` - Symbolically link files from the cache

Environment variable: `UV_LINK_MODE`

## Examples

### Create default virtual environment

```bash theme={null}
uv venv
```

Creates `.venv` in the current directory.

### Create with custom path

```bash theme={null}
uv venv myenv
```

Creates a virtual environment at `./myenv`.

### Create with specific Python version

```bash theme={null}
uv venv --python 3.12
```

If Python 3.12 is not installed, uv will download and install it automatically.

### Create with Python path

```bash theme={null}
uv venv --python /usr/bin/python3.11
```

Uses a specific Python executable.

### Create with seed packages

```bash theme={null}
uv venv --seed
```

Installs `pip`, and (for Python \< 3.12) `setuptools` and `wheel`.

### Create relocatable environment

```bash theme={null}
uv venv --relocatable
```

Useful for creating environments that can be moved or redistributed.

### Replace existing environment

```bash theme={null}
uv venv --clear
```

Removes existing `.venv` and creates a new one.

### Create with custom prompt

```bash theme={null}
uv venv --prompt myproject
```

When activated, the shell prompt will show `(myproject)`.

### Create with system site packages

```bash theme={null}
uv venv --system-site-packages
```

Gives the environment access to system-installed packages.

### Create with PyPy

```bash theme={null}
uv venv --python pypy3.10
```

Creates a virtual environment using PyPy instead of CPython.

## Use cases

### Project isolation

Create isolated environments for different projects:

```bash theme={null}
cd project-a
uv venv

cd ../project-b
uv venv
```

Each project gets its own `.venv` with isolated dependencies.

### Testing multiple Python versions

Test your code across Python versions:

```bash theme={null}
uv venv venv-py310 --python 3.10
uv venv venv-py311 --python 3.11
uv venv venv-py312 --python 3.12
```

### Compatibility with legacy tools

Some tools expect `pip` to be available:

```bash theme={null}
uv venv --seed
```

This ensures compatibility while still using uv for most operations.

### Portable environments

Create environments that can be moved:

```bash theme={null}
uv venv --relocatable
```

Useful for bundling applications or creating portable development environments.

## Working with virtual environments

### Activation (optional)

While uv doesn't require activation, you can still activate environments:

```bash theme={null}
# On Unix/macOS
source .venv/bin/activate

# On Windows
.venv\Scripts\activate
```

### Using without activation

uv automatically detects and uses `.venv`:

```bash theme={null}
# These commands automatically use .venv
uv pip install requests
uv pip list
uv run python script.py
```

### Deactivation

If activated:

```bash theme={null}
deactivate
```

## Differences from venv

### Faster creation

uv creates virtual environments significantly faster than the standard library `venv` module.

### Automatic Python installation

uv can download and install Python versions automatically:

```bash theme={null}
uv venv --python 3.12  # Downloads Python 3.12 if not available
```

### No activation required

uv automatically finds and uses `.venv` without activation.

### Relocatable by default (optional)

uv can create relocatable environments with `--relocatable`.

## Related commands

* [`uv python install`](/cli/python-install) - Install Python versions
* [`uv pip install`](/cli/pip-install) - Install packages into the environment
* [`uv run`](/cli/run) - Run commands in the project environment

## Notes

* Virtual environments are created quickly using uv's optimized implementation
* By default, uv does not install seed packages (`pip`, `setuptools`, `wheel`) unless `--seed` is specified
* The environment does not need to be activated when using uv commands
* uv can automatically download Python versions if they're not installed
* Use `--clear` to replace an existing environment
* The `UV_PROJECT_ENVIRONMENT` environment variable can override the default `.venv` path for projects