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

> Add dependencies to a Python project

Add dependencies to the project's `pyproject.toml`.

## Usage

```bash theme={null}
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

<ParamField path="PACKAGES" type="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.
</ParamField>

## Options

### Source Options

<ParamField path="--requirements" type="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`
</ParamField>

<ParamField path="--constraints" type="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`
</ParamField>

### Dependency Groups

<ParamField path="--dev" flag>
  Add the requirements to the development dependency group.

  This option is an alias for `--group dev`.

  Environment variable: `UV_DEV`
</ParamField>

<ParamField path="--optional" type="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`.
</ParamField>

<ParamField path="--group" type="string">
  Add the requirements to the specified dependency group.

  These requirements will not be included in the published metadata for the project.
</ParamField>

### Version Specification

<ParamField path="--marker" type="string">
  Apply this marker to all added packages.

  Short form: `-m`
</ParamField>

<ParamField path="--raw" flag>
  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.
</ParamField>

<ParamField path="--bounds" type="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.
</ParamField>

### Git Options

<ParamField path="--rev" type="string">
  Commit to use when adding a dependency from Git.
</ParamField>

<ParamField path="--tag" type="string">
  Tag to use when adding a dependency from Git.
</ParamField>

<ParamField path="--branch" type="string">
  Branch to use when adding a dependency from Git.
</ParamField>

<ParamField path="--lfs" flag>
  Whether to use Git LFS when adding a dependency from Git.
</ParamField>

### Installation Options

<ParamField path="--editable" flag>
  Add the requirements as editable.
</ParamField>

<ParamField path="--no-editable" flag>
  Don't add the requirements as editable.

  Environment variable: `UV_NO_EDITABLE`
</ParamField>

<ParamField path="--extra" type="string[]">
  Extras to enable for the dependency.

  May be provided more than once.

  To add this dependency to an optional extra instead, see `--optional`.
</ParamField>

<ParamField path="--no-sync" flag>
  Avoid syncing the virtual environment.

  Environment variable: `UV_NO_SYNC`
</ParamField>

### Locking Options

<ParamField path="--locked" flag>
  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`
</ParamField>

<ParamField path="--frozen" flag>
  Add dependencies without re-locking the project.

  The project environment will not be synced.

  Environment variable: `UV_FROZEN`
</ParamField>

### Workspace Options

<ParamField path="--package" type="string">
  Add the dependency to a specific package in the workspace.
</ParamField>

<ParamField path="--script" type="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.
</ParamField>

<ParamField path="--workspace" flag>
  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.
</ParamField>

<ParamField path="--no-workspace" flag>
  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.
</ParamField>

### Environment Options

<ParamField path="--active" flag>
  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.
</ParamField>

<ParamField path="--python" type="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`
</ParamField>

### Selective Installation

<ParamField path="--no-install-project" flag>
  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.
</ParamField>

<ParamField path="--no-install-workspace" flag>
  Do not install any workspace members, including the current project.
</ParamField>

<ParamField path="--no-install-local" flag>
  Do not install local path dependencies.

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

<ParamField path="--no-install-package" type="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.
</ParamField>

## Examples

### Add a single package

```bash theme={null}
uv add requests
```

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

### Add multiple packages

```bash theme={null}
uv add fastapi uvicorn
```

### Add a package with a specific version

```bash theme={null}
uv add "ruff==0.5.0"
```

### Add a package with a version constraint

```bash theme={null}
uv add "django>=4.0,<5.0"
```

### Add a development dependency

```bash theme={null}
uv add --dev pytest black ruff
```

### Add an optional dependency

```bash theme={null}
uv add --optional docs sphinx sphinx-rtd-theme
```

### Add from a requirements file

```bash theme={null}
uv add --requirements requirements.txt
```

### Add a Git dependency

```bash theme={null}
uv add git+https://github.com/user/repo.git
```

With a specific branch:

```bash theme={null}
uv add --branch main git+https://github.com/user/repo.git
```

With a specific tag:

```bash theme={null}
uv add --tag v1.0.0 git+https://github.com/user/repo.git
```

### Add a local editable dependency

```bash theme={null}
uv add --editable ../my-local-package
```

### Add with extras

```bash theme={null}
uv add "fastapi[all]"
```

Or using the `--extra` flag:

```bash theme={null}
uv add --extra all fastapi
```

### Add to a specific dependency group

```bash theme={null}
uv add --group test pytest pytest-cov
```

### Add to a workspace package

```bash theme={null}
uv add --package my-package requests
```

### Add to a Python script

```bash theme={null}
uv add --script my_script.py requests beautifulsoup4
```

## Common Patterns

### Setting up a web application

```bash theme={null}
uv add fastapi uvicorn
uv add --dev pytest httpx black ruff
```

### Adding data science packages

```bash theme={null}
uv add pandas numpy matplotlib
uv add --dev jupyter notebook
```

### Adding packages without syncing

```bash theme={null}
uv add --no-sync package1 package2
uv sync  # Sync later
```

### Adding from GitHub with specific commit

```bash theme={null}
uv add --rev abc123 git+https://github.com/user/repo.git
```

## Related Commands

* [`uv remove`](/cli/remove) - Remove dependencies from the project
* [`uv sync`](/cli/sync) - Sync the project environment
* [`uv lock`](/cli/lock) - Update the project lockfile
* [`uv init`](/cli/init) - Create a new project