pyproject.toml.
Usage
Description
Add dependencies to the project’spyproject.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
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
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: -rConstrain versions using the given requirements files.Constraints files are
Environment variable:
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: -cEnvironment variable:
UV_CONSTRAINTDependency Groups
--dev
Add the requirements to the development dependency group.This option is an alias for
--group dev.Environment variable: UV_DEVAdd 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.Add the requirements to the specified dependency group.These requirements will not be included in the published metadata for the project.
Version Specification
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.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)
Git Options
Commit to use when adding a dependency from Git.
Tag to use when adding a dependency from Git.
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_EDITABLEExtras 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_SYNCLocking 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_FROZENWorkspace Options
Add the dependency to a specific package in the workspace.
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.
The Python interpreter to use for resolving and syncing.See
Environment variable:
uv help python for details on Python discovery and supported request formats.Short form: -pEnvironment variable:
UV_PYTHONSelective 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.
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
requests with a lower bound constraint (e.g., requests>=2.31.0).
Add multiple packages
Add a package with a specific version
Add a package with a version constraint
Add a development dependency
Add an optional dependency
Add from a requirements file
Add a Git dependency
Add a local editable dependency
Add with extras
--extra flag: