diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 7e4a7210104b9..3a6424094bdce 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -3562,7 +3562,7 @@ pub struct IndexArgs { /// indexes. /// /// If a path, the target must be a directory that contains packages as wheel files (`.whl`) or - /// source distributions (`.tar.gz` or `.zip`) at the top level. + /// source distributions (usually `.tar.gz` or `.zip`) at the top level. /// /// If a URL, the page must contain a flat list of links to package files adhering to the /// formats described above. diff --git a/crates/uv-settings/src/settings.rs b/crates/uv-settings/src/settings.rs index 7e3b1649ed073..893164d9def45 100644 --- a/crates/uv-settings/src/settings.rs +++ b/crates/uv-settings/src/settings.rs @@ -318,7 +318,7 @@ pub struct ResolverInstallerOptions { /// indexes. /// /// If a path, the target must be a directory that contains packages as wheel files (`.whl`) or - /// source distributions (`.tar.gz` or `.zip`) at the top level. + /// source distributions (usually `.tar.gz` or `.zip`) at the top level. /// /// If a URL, the page must contain a flat list of links to package files adhering to the /// formats described above. @@ -705,7 +705,7 @@ pub struct PipOptions { /// indexes. /// /// If a path, the target must be a directory that contains packages as wheel files (`.whl`) or - /// source distributions (`.tar.gz` or `.zip`) at the top level. + /// source distributions (usually `.tar.gz` or `.zip`) at the top level. /// /// If a URL, the page must contain a flat list of links to package files adhering to the /// formats described above. diff --git a/docs/concepts/dependencies.md b/docs/concepts/dependencies.md index d65e586f60414..d58d72954101b 100644 --- a/docs/concepts/dependencies.md +++ b/docs/concepts/dependencies.md @@ -128,7 +128,8 @@ A `subdirectory` may be specified if the package isn't in the repository root. ### URL To add a URL source, provide a `https://` URL to either a wheel (ending in `.whl`) or a source -distribution (ending in `.zip` or `.tar.gz`). +distribution (usually ending in `.tar.gz` or `.zip`, +see [here](../concepts/resolution.md#source-distribution) for all supported formats). For example: @@ -149,13 +150,14 @@ httpx = { url = "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b280 ``` URL dependencies can also be manually added or edited in the `pyproject.toml` with the -`{ url = }` syntax. A `subdirectory` may be specified if the if the source distribution isn't -in the archive root. +`{ url = }` syntax. A `subdirectory` may be specified if the source distribution isn't in the +archive root. ### Path -To add a path source, provide the path of a wheel (ending in `.whl`), a source distribution (ending -in `.zip` or `.tar.gz`), or a directory containing a `pyproject.toml`. +To add a path source, provide the path of a wheel (ending in `.whl`), a source distribution (usually +ending in `.tar.gz` or `.zip`, see [here](../concepts/resolution.md#source-distribution) for all +supported formats), or a directory containing a `pyproject.toml`. For example: diff --git a/docs/concepts/projects.md b/docs/concepts/projects.md index 65e361e7fa0fa..735c569166d09 100644 --- a/docs/concepts/projects.md +++ b/docs/concepts/projects.md @@ -560,9 +560,9 @@ To distribute your project to others (e.g., to upload it to an index like PyPI), build it into a distributable format. Python projects are typically distributed as both source distributions (sdists) and binary -distributions (wheels). The former is a `.tar.gz` file containing the project's source code along -with some additional metadata, while the latter is a `.whl` file containing pre-built artifacts that -can be installed directly. +distributions (wheels). The former is usually a `.tar.gz` or `.zip` file containing the project's +source code along with some additional metadata, while the latter is a `.whl` file containing +pre-built artifacts that can be installed directly. `uv build` can be used to build both source distributions and binary distributions for your project. By default, `uv build` will build the project in the current directory, and place the built diff --git a/docs/concepts/resolution.md b/docs/concepts/resolution.md index 0df0ce80f07cc..6f47e96da18de 100644 --- a/docs/concepts/resolution.md +++ b/docs/concepts/resolution.md @@ -296,6 +296,18 @@ To ensure reproducibility, messages for unsatisfiable resolutions will not menti distributions were excluded due to the `--exclude-newer` flag — newer distributions will be treated as if they do not exist. +## Source distribution + +Most packages publish their source distributions as gzip tarball (`.tar.gz`) or zip (`.zip`) +archives, but while less common, other formats exist. uv supports the following formats and +extensions when reading and extracting source distributions: + +- bzip2 tarball (`.tar.bz2`) +- gzip tarball (`.tar.gz`) +- xz tarball (`.tar.xz`) +- zip (`.zip`) +- zstd tarball (`.tar.zst`) + ## Learn more For more details about the internals of the resolver, see the diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 214e13b0e760d..2f03a9f8c57aa 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -136,7 +136,7 @@ uv run [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -610,7 +610,7 @@ uv add [OPTIONS] >

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -910,7 +910,7 @@ uv remove [OPTIONS] ...

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -1198,7 +1198,7 @@ uv sync [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -1479,7 +1479,7 @@ uv lock [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -1742,7 +1742,7 @@ uv export [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -2028,7 +2028,7 @@ uv tree [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -2383,7 +2383,7 @@ uv tool run [OPTIONS] [COMMAND]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -2651,7 +2651,7 @@ uv tool install [OPTIONS]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -2919,7 +2919,7 @@ uv tool upgrade [OPTIONS] ...

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -4302,7 +4302,7 @@ uv pip compile [OPTIONS] ...

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -4674,7 +4674,7 @@ uv pip sync [OPTIONS] ...

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -5000,7 +5000,7 @@ uv pip install [OPTIONS] |--editable May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -6057,7 +6057,7 @@ uv venv [OPTIONS] [PATH]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

@@ -6282,7 +6282,7 @@ uv build [OPTIONS] [SRC]

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

-

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.tar.gz or .zip) at the top level.

+

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (usually .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

diff --git a/docs/reference/settings.md b/docs/reference/settings.md index 0fe5287a153d9..e39d6ecfc893f 100644 --- a/docs/reference/settings.md +++ b/docs/reference/settings.md @@ -370,7 +370,7 @@ Locations to search for candidate distributions, in addition to those found in t indexes. If a path, the target must be a directory that contains packages as wheel files (`.whl`) or -source distributions (`.tar.gz` or `.zip`) at the top level. +source distributions (usually `.tar.gz` or `.zip`) at the top level. If a URL, the page must contain a flat list of links to package files adhering to the formats described above. @@ -1662,7 +1662,7 @@ Locations to search for candidate distributions, in addition to those found in t indexes. If a path, the target must be a directory that contains packages as wheel files (`.whl`) or -source distributions (`.tar.gz` or `.zip`) at the top level. +source distributions (usually `.tar.gz` or `.zip`) at the top level. If a URL, the page must contain a flat list of links to package files adhering to the formats described above. diff --git a/uv.schema.json b/uv.schema.json index 07867fe9ee75e..7c813bfef67d6 100644 --- a/uv.schema.json +++ b/uv.schema.json @@ -118,7 +118,7 @@ } }, "find-links": { - "description": "Locations to search for candidate distributions, in addition to those found in the registry indexes.\n\nIf a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (`.tar.gz` or `.zip`) at the top level.\n\nIf a URL, the page must contain a flat list of links to package files adhering to the formats described above.", + "description": "Locations to search for candidate distributions, in addition to those found in the registry indexes.\n\nIf a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (usually `.tar.gz` or `.zip`) at the top level.\n\nIf a URL, the page must contain a flat list of links to package files adhering to the formats described above.", "type": [ "array", "null" @@ -698,7 +698,7 @@ } }, "find-links": { - "description": "Locations to search for candidate distributions, in addition to those found in the registry indexes.\n\nIf a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (`.tar.gz` or `.zip`) at the top level.\n\nIf a URL, the page must contain a flat list of links to package files adhering to the formats described above.", + "description": "Locations to search for candidate distributions, in addition to those found in the registry indexes.\n\nIf a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (usually `.tar.gz` or `.zip`) at the top level.\n\nIf a URL, the page must contain a flat list of links to package files adhering to the formats described above.", "type": [ "array", "null"