diff --git a/docs/concepts/projects.md b/docs/concepts/projects.md index cbe9648c712b..b6420eda8525 100644 --- a/docs/concepts/projects.md +++ b/docs/concepts/projects.md @@ -513,6 +513,37 @@ dependencies listed. If working in a project composed of many packages, see the [workspaces](./workspaces.md) documentation. +## Building projects + +To distribute your project to others (e.g., to upload it to an index like PyPI), you'll need to +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. + +`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 +artifacts in a `dist/` subdirectory: + +```console +$ uv build +$ ls dist/ +example-0.1.0-py3-none-any.whl +example-0.1.0.tar.gz +``` + +You can build the project in a different directory by providing a path to `uv build`, e.g., +`uv build path/to/project`. + +`uv build` will first build a source distribution, and then build a binary distribution (wheel) from +that source distribution. + +You can limit `uv build` to building a source distribution with `uv build --source`, a binary +distribution with `uv build --binary`, or build both distributions from source with +`uv build --source --binary`. + ## Build isolation By default, uv builds all packages in isolated virtual environments, as per diff --git a/docs/guides/projects.md b/docs/guides/projects.md index 46613e318293..c5a477ffed1b 100644 --- a/docs/guides/projects.md +++ b/docs/guides/projects.md @@ -175,6 +175,24 @@ $ python example.py See the documentation on [running commands](../concepts/projects.md#running-commands) and [running scripts](../concepts/projects.md#running-scripts) in projects for more details. +## Building distributions + +`uv build` can be used to build source distributions and binary distributions (wheel) for your +project. + +By default, `uv build` will build the project in the current directory, and place the built +artifacts in a `dist/` subdirectory: + +```console +$ uv build +$ ls dist/ +hello-world-0.1.0-py3-none-any.whl +hello-world-0.1.0.tar.gz +``` + +See the documentation on [building projects](../concepts/projects.md#building-projects) for more +details. + ## Next steps To learn more about working on projects with uv, see the [Projects concept](../concepts/projects.md) diff --git a/docs/guides/publish.md b/docs/guides/publish.md index 4dd582e8b44c..537d088eb4b0 100644 --- a/docs/guides/publish.md +++ b/docs/guides/publish.md @@ -1,8 +1,10 @@ # Publishing a package -uv does not yet have dedicated commands for building and publishing a package. Instead, you can use -the PyPA tools [`build`](https://github.com/pypa/build) and -[`twine`](https://github.com/pypa/twine), both of which can be invoked via `uvx`. +uv supports building Python packages into source and binary distributions via `uv build`. + +As uv does not yet have a dedicated command for publishing packages, you can use the PyPA tool +[`twine`](https://github.com/pypa/twine) to upload your package to a package registry, which can be +invoked via `uvx`. ## Preparing your project for packaging @@ -16,18 +18,17 @@ the effect of declaring a build system in the ## Building your package -Build your package with the official `build` frontend: +Build your package with `uv build`: ```console -$ uvx --from build pyproject-build --installer uv +$ uv build ``` -!!! note - - Using `--installer uv` is not required, but uses uv instead of the default, pip, for faster - builds. +By default, `uv build` will build the project in the current directory, and place the built +artifacts in a `dist/` subdirectory. -The build artifacts will be placed in `dist/`. +Alternatively, `uv build ` will build the package in the specified directory, while +`uv build --package ` will build the specified package within the current workspace. ## Publishing your package