uv add

Add dependencies to a Python project

Add dependencies to the project’s pyproject.toml.

Usage

uv add [OPTIONS] <PACKAGES>...

Description

Add dependencies to the project’s pyproject.toml file.

If a given dependency exists already, it will be updated to the new version specifier unless it includes markers that differ from the existing specifier, in which case another entry for the dependency will be added.

The lockfile and project environment will be updated to reflect the added dependencies. To skip updating the lockfile, use --frozen. To skip updating the environment, use --no-sync.

If any of the requested dependencies cannot be found, uv will exit with an error, unless the --frozen flag is provided, in which case uv will add the dependencies verbatim without checking that they exist or are compatible with the project.

uv will search for a project in the current directory or any parent directory. If a project cannot be found, uv will exit with an error.

Arguments

PACKAGES · string[] · required

The packages to add, as PEP 508 requirements (e.g., ruff==0.5.0).

Can also use --requirements to add packages from a file.

Options

Source Options

--requirements · path

Add the packages listed in the given files.

The following formats are supported: requirements.txt, .py files with inline metadata, pylock.toml, pyproject.toml, setup.py, and setup.cfg.

Short form: -r

--constraints · path

Constrain versions using the given requirements files.

Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. The constraints will not be added to the project’s pyproject.toml file, but will be respected during dependency resolution.

This is equivalent to pip’s --constraint option.

Short form: -c
Environment variable: UV_CONSTRAINT

Dependency Groups

--dev

Add the requirements to the development dependency group.

This option is an alias for --group dev.

Environment variable: UV_DEV

--optional · string

Add the requirements to the package’s optional dependencies for the specified extra.

The group may then be activated when installing the project with the --extra flag.

To enable an optional extra for this requirement instead, see --extra.

--group · string

Add the requirements to the specified dependency group.

These requirements will not be included in the published metadata for the project.

Version Specification

--marker · string

Apply this marker to all added packages.

Short form: -m

--raw

Add a dependency as provided.

By default, uv will use the tool.uv.sources section to record source information for Git, local, editable, and direct URL requirements. When --raw is provided, uv will add source requirements to project.dependencies, rather than tool.uv.sources.

Additionally, by default, uv will add bounds to your dependency, e.g., foo>=1.0.0. When --raw is provided, uv will add the dependency without bounds.

--bounds · string

The kind of version specifier to use when adding dependencies.

When adding a dependency to the project, if no constraint or URL is provided, a constraint is added based on the latest compatible version of the package. By default, a lower bound constraint is used, e.g., >=1.2.3.

When --frozen is provided, no resolution is performed, and dependencies are always added without constraints.

Options:

• lower - Add a lower bound (e.g., >=1.2.3)
• exact - Add an exact version (e.g., ==1.2.3)
• compatible - Add a compatible version (e.g., ~=1.2.3)

This option is in preview and may change in any future release.

Git Options

--rev · string

Commit to use when adding a dependency from Git.

--tag · string

Tag to use when adding a dependency from Git.

--branch · string

Branch to use when adding a dependency from Git.

--lfs

Whether to use Git LFS when adding a dependency from Git.

Installation Options

--editable

Add the requirements as editable.

--no-editable

Don’t add the requirements as editable.

Environment variable: UV_NO_EDITABLE

--extra · string[]

Extras to enable for the dependency.

May be provided more than once.

To add this dependency to an optional extra instead, see --optional.

--no-sync

Avoid syncing the virtual environment.

Environment variable: UV_NO_SYNC

Locking Options

--locked

Assert that the uv.lock will remain unchanged.

Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.

Environment variable: UV_LOCKED

--frozen

Add dependencies without re-locking the project.

The project environment will not be synced.

Environment variable: UV_FROZEN

Workspace Options

--package · string

Add the dependency to a specific package in the workspace.

--script · path

Add the dependency to the specified Python script, rather than to a project.

If provided, uv will add the dependency to the script’s inline metadata table, in adherence with PEP 723. If no such inline metadata table is present, a new one will be created and added to the script.

--workspace

Add the dependency as a workspace member.

By default, uv will add path dependencies that are within the workspace directory as workspace members. When used with a path dependency, the package will be added to the workspace’s members list in the root pyproject.toml file.

--no-workspace

Don’t add the dependency as a workspace member.

By default, when adding a dependency that’s a local path and is within the workspace directory, uv will add it as a workspace member; pass --no-workspace to add the package as direct path dependency instead.

Environment Options

--active

Prefer the active virtual environment over the project’s virtual environment.

If the project virtual environment is active or no virtual environment is active, this has no effect.

--python · string

The Python interpreter to use for resolving and syncing.

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

Short form: -p
Environment variable: UV_PYTHON

Selective Installation

--no-install-project

Do not install the current project.

By default, the current project is installed into the environment with all of its dependencies. The --no-install-project option allows the project to be excluded, but all of its dependencies are still installed.

--no-install-workspace

Do not install any workspace members, including the current project.

--no-install-local

Do not install local path dependencies.

Skips the current project, workspace members, and any other local (path or editable) packages.

--no-install-package · string[]

Do not install the given package(s).

By default, all project’s dependencies are installed into the environment. The --no-install-package option allows exclusion of specific packages.

Examples

Add a single package

uv add requests

Adds the latest version of requests with a lower bound constraint (e.g., requests>=2.31.0).

Add multiple packages

uv add fastapi uvicorn

Add a package with a specific version

uv add "ruff==0.5.0"

Add a package with a version constraint

uv add "django>=4.0,<5.0"

Add a development dependency

uv add --dev pytest black ruff

Add an optional dependency

uv add --optional docs sphinx sphinx-rtd-theme

Add from a requirements file

uv add --requirements requirements.txt

Add a Git dependency

uv add git+https://github.com/user/repo.git

With a specific branch:

uv add --branch main git+https://github.com/user/repo.git

With a specific tag:

uv add --tag v1.0.0 git+https://github.com/user/repo.git

Add a local editable dependency

uv add --editable ../my-local-package

Add with extras

uv add "fastapi[all]"

Or using the --extra flag:

uv add --extra all fastapi

Add to a specific dependency group

uv add --group test pytest pytest-cov

Add to a workspace package

uv add --package my-package requests

Add to a Python script

uv add --script my_script.py requests beautifulsoup4

Common Patterns

Setting up a web application

uv add fastapi uvicorn
uv add --dev pytest httpx black ruff

Adding data science packages

uv add pandas numpy matplotlib
uv add --dev jupyter notebook

Adding packages without syncing

uv add --no-sync package1 package2
uv sync  # Sync later

Adding from GitHub with specific commit

uv add --rev abc123 git+https://github.com/user/repo.git

Related Commands

• uv remove - Remove dependencies from the project
• uv sync - Sync the project environment
• uv lock - Update the project lockfile
• uv init - Create a new project