uv/docs/specifying_dependencies.md

Warning: this documentation applies to a future version of uv. Please refer to README.md for documentation for the latest release.

Specifying dependencies

In uv, dependency specification is divided between two tables: project.dependencies and tool.uv.sources.

At a high-level, the former is used to define the standards-compliant dependency metadata, propagated when uploading to PyPI or building a wheel. The latter is used to specify the sources required to install the dependencies, which can come from a Git repository, a URL, a local path, a different index, etc.

project.dependencies

The project.dependencies table represents the dependencies that are used when uploading to PyPI or building a wheel. Individual dependencies are specified using [PEP 508](#PEP 508), and the table as a whole follows the PEP 621 standard.

You should think of project.dependencies as defining the packages that are required for your project, along with the version constraints that should be used when installing them.

project.dependencies is structured as a list in which each entry includes a dependency name and version, and optionally extras or environment markers for platform-specific packages, as in:

[project]
name = "albatross"
version = "0.1.0"
dependencies = [
  # Any version in this range
  "tqdm >=4.66.2,<5",
  # Exactly this version of torch
  "torch ==2.2.2",
  # Install transformers with the torch extra
  "transformers[torch] >=4.39.3,<5",
  # Only install this package on older python versions
  # See "Environment Markers" for more information
  "importlib_metadata >=7.1.0,<8; python_version < '3.10'",
  "mollymawk ==0.1.0"
]

If you only require packages from PyPI or a single --index-url, then project.dependencies is all you need. If, however, you depend on local packages, Git dependencies, or packages from a different index, you should use tool.uv.sources.

tool.uv.sources

During development, you may rely on a package that isn't available on PyPI. For example, let’s say that we need to pull in a version of tqdm from a specific Git commit, importlib_metadata from a dedicated URL, torch from the PyTorch-specific index, and mollymawk from our own workspace.

We can express these requirements by enriching the project.dependencies table with tool.uv.sources:

[project]
name = "albatross"
version = "0.1.0"
dependencies = [
  # Any version in this range.
  "tqdm >=4.66.2,<5",
  # Exactly this version of torch.
  "torch ==2.2.2",
  # Install transformers with the torch extra.
  "transformers[torch] >=4.39.3,<5",
  # Only install this package on Python versions prior to 3.10.
  "importlib_metadata >=7.1.0,<8; python_version < '3.10'",
  "mollymawk ==0.1.0"
]

[tool.uv.sources]
# Install a specific Git commit.
tqdm = { git = "https://github.com/tqdm/tqdm", rev = "cc372d09dcd5a5eabdc6ed4cf365bdb0be004d44" }
# Install a remote source distribution (`.zip`, `.tar.gz`) or wheel (`.whl`).
importlib_metadata = { url = "https://github.com/python/importlib_metadata/archive/refs/tags/v7.1.0.zip" }
# Pin a dependency for a specific registry.
torch = { index = "torch-cu118" }
# Use a package included in the same repository (editable installation).
mollymawk = { workspace = true }

# See "Workspaces".
[tool.uv.workspace]
include = [
  "packages/mollymawk"
]

# See "Indexes".
[tool.uv.indexes]
torch-cu118 = "https://download.pytorch.org/whl/cu118"

We support the following sources (which are mutually exclusive for a given dependency):

• Git: Use git with a Git URL, optionally one of rev, tag, or branch, and optionally a subdirectoy, if the package isn't in the repository root.
• URL: A url key with an https:// URL to a wheel (ending in .whl) or a source distribution (ending in .zip or .tar.gz), and optionally a subdirectory if the source distribution isn't in the archive root.
• Path: The path is an absolute or relative path to a wheel (ending in .whl), a source distribution (ending in .zip or .tar.gz), or a directory containing a pyproject.toml. We recommend using workspaces over manual path dependencies. For directories, you can specify editable = true for an editable installation.
• Index: Set the index key to the name of an index name to install it from this registry instead of your default index.
• Workspace: Set workspace = true to use the workspace dependency. You need to explicitly require all workspace dependencies you use. They are editable by default; specify editable = false to install them as regular dependencies.

Note that if a non-uv project uses this project as a Git- or path-dependency, only project.dependencies is transferred, and you'll need to apply the information in the source table using the configuration of the other project's package manager.

Optional dependencies

For libraries, you may want to make certain features and their dependencies optional. For example, pandas has an excel extra and a plot extra to limit the installation of Excel parsers and (e.g.) matplotlib to those that explicitly require them. In the case of Pandas, you can install those extras with: pandas[plot, excel].

Optional dependencies are specified in [project.optional-dependencies], a TOML table that maps from extra name to its dependencies, following the [PEP 508](#PEP 508) syntax.

tool.uv.sources applies to this table equally.

[project]
name = "pandas"
version = "1.0.0"

[project.optional-dependencies]
plot = [
  "matplotlib>=3.6.3"
]
excel = [
  "odfpy>=1.4.1",
  "openpyxl>=3.1.0",
  "python-calamine>=0.1.7",
  "pyxlsb>=1.0.10",
  "xlrd>=2.0.1",
  "xlsxwriter>=3.0.5"
]

Development dependencies

N.B. This feature is not yet implemented.

Unlike optional dependencies, development dependencies are local-only and will not be published to PyPI or other indexes. As such, development dependencies are included under [tool.uv] instead of [project]. tool.uv.sources applies to them equally.

[tool.uv]
dev-dependencies = [
  "pytest >=8.1.1,<9"
]

You can also put development dependencies into groups and install them individually:

[tool.uv.dev-dependencies]
test = [
  "pytest >=8.1.1,<9"
]
lint = [
  "mypy >=1,<2"
]

[tool.uv]
default-dev-dependencies = ["test"]

PEP 508

The PEP 508 syntax allows you to specify, in order:

• The dependency name
• The extras you want (optional)
• The version specifier
• An environment marker (optional)

The version specifiers are comma separated and added together, e.g., foo >=1.2.3,<2,!=1.4.0 is interpreted as "a version of foo that's at least 1.2.3, but less than 2, and not 1.4.0".

Specifiers are padded with trailing zeros if required, so foo ==2 matches foo 2.0.0, too.

You can use a star for the last digit with equals, e.g. foo ==2.1.* will accept any release from the 2.1 series. Similarly, ~= matches where the last digit is equal or higher, e.g., foo ~=1.2 is equal to foo >=1.2,<2, and foo ~=1.2.3 is equal to foo >=1.2.3,<1.3.

Extras are comma-separated in square bracket between name and version, e.g., pandas[excel,plot] ==2.2.

Some dependencies are only required in specific environments, e.g., a specific Python version or operating system. For example to install the importlib-metadata backport for the importlib.metadata module, you would use importlib-metadata >=7.1.0,<8; python_version < '3.10'. To install colorama on Windows (but omit it on other platforms), use colorama >=0.4.6,<5; platform_system == "Windows".

You combine markers with and and or and parentheses, e.g., aiohttp >=3.7.4,<4; (sys_platform != 'win32' or implementation_name != 'pypy') and python_version >= '3.10'. Note that versions within markers must be quoted, while versions outside of markers must not be quoted.

Editables

A regular installation of a directory with a Python package first builds a wheel and then installs that wheel into your virtual environment, copying all source files. When you edit the source files, the virtual environment will contain outdated versions.

Editable installations instead add a link to the project within the virtual environment (a .pth file), which instructs the interpreter to include your sources directly.

There are some limitations to editables (mainly: your build backend needs to support them, and native modules aren't recompiled before import), but they are useful for development, as your virtual environment will always use the latest version of your package.

uv uses editable installation for workspace packages and patched dependencies by default.