uv venv

Create a virtual environment

uv venv

Create a virtual environment.

Usage

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.

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

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

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

uv venv

Creates .venv in the current directory.

Create with custom path

uv venv myenv

Creates a virtual environment at ./myenv.

Create with specific Python version

uv venv --python 3.12

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

Create with Python path

uv venv --python /usr/bin/python3.11

Uses a specific Python executable.

Create with seed packages

uv venv --seed

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

Create relocatable environment

uv venv --relocatable

Useful for creating environments that can be moved or redistributed.

Replace existing environment

uv venv --clear

Removes existing .venv and creates a new one.

Create with custom prompt

uv venv --prompt myproject

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

Create with system site packages

uv venv --system-site-packages

Gives the environment access to system-installed packages.

Create with PyPy

uv venv --python pypy3.10

Creates a virtual environment using PyPy instead of CPython.

Use cases

Project isolation

Create isolated environments for different projects:

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:

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:

uv venv --seed

This ensures compatibility while still using uv for most operations.

Portable environments

Create environments that can be moved:

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:

# On Unix/macOS
source .venv/bin/activate

# On Windows
.venv\Scripts\activate

Using without activation

uv automatically detects and uses .venv:

# These commands automatically use .venv
uv pip install requests
uv pip list
uv run python script.py

Deactivation

If activated:

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:

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 - Install Python versions
• uv pip install - Install packages into the environment
• uv 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