diff --git a/README.md b/README.md index 25816ed0b..74e1b56d9 100644 --- a/README.md +++ b/README.md @@ -26,17 +26,17 @@ An extremely fast Python package and project manager, written in Rust. - 🚀 A single tool to replace `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `twine`, `virtualenv`, and more. - ⚡️ [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip`. -- 🐍 [Installs and manages](#python-management) Python versions. -- 🛠️ [Runs and installs](#tool-management) Python applications. -- ❇️ [Runs single-file scripts](#script-support), with support for - [inline dependency metadata](https://docs.astral.sh/uv/guides/scripts#declaring-script-dependencies). -- 🗂️ Provides [comprehensive project management](#project-management), with a - [universal lockfile](https://docs.astral.sh/uv/concepts/projects#project-lockfile). -- 🔩 Includes a [pip-compatible interface](#a-pip-compatible-interface) for a performance boost with - a familiar CLI. -- 🏢 Supports Cargo-style [workspaces](https://docs.astral.sh/uv/concepts/workspaces) for scalable - projects. -- 💾 Disk-space efficient, with a [global cache](https://docs.astral.sh/uv/concepts/cache) for +- 🗂️ Provides [comprehensive project management](#project), with a + [universal lockfile](https://docs.astral.sh/uv/concepts/projects/layout.md#the-lockfile). +- ❇️ [Runs scripts](#script-support), with support for + [inline dependency metadata](https://docs.astral.sh/uv/guides/scripts.md#declaring-script-dependencies). +- 🐍 [Installs and manages](#python-versions) Python versions. +- 🛠️ [Runs and installs](#tool) tools published as Python packages. +- 🔩 Includes a [pip-compatible interface](#the-pip-interface) for a performance boost with a + familiar CLI. +- 🏢 Supports Cargo-style [workspaces](https://docs.astral.sh/uv/concepts/projects/workspaces.md) + for scalable projects. +- 💾 Disk-space efficient, with a [global cache](https://docs.astral.sh/uv/concepts/cache.md) for dependency deduplication. - ⏬ Installable without Rust or Python via `curl` or `pip`. - 🖥️ Supports macOS, Linux, and Windows. @@ -87,7 +87,7 @@ Additionally, the command line reference documentation can be viewed with `uv he ## Features -### Project management +### Projects uv manages project dependencies and environments, with support for lockfiles, workspaces, and more, similar to `rye` or `poetry`: @@ -109,6 +109,13 @@ Installed 2 packages in 1ms $ uv run ruff check All checks passed! + +$ uv lock +Resolved 2 packages in 0.33ms + +$ uv sync +Resolved 2 packages in 0.70ms +Audited 1 package in 0.02ms ``` See the [project documentation](https://docs.astral.sh/uv/guides/projects/) to get started. @@ -116,7 +123,31 @@ See the [project documentation](https://docs.astral.sh/uv/guides/projects/) to g uv also supports building and publishing projects, even if they're not managed with uv. See the [publish guide](https://docs.astral.sh/uv/guides/publish/) to learn more. -### Tool management +### Scripts + +uv manages dependencies and environments for single-file scripts. + +Create a new script and add inline metadata declaring its dependencies: + +```console +$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py + +$ uv add --script example.py requests +Updated `example.py` +``` + +Then, run the script in an isolated virtual environment: + +```console +$ uv run example.py +Reading inline script metadata from: example.py +Installed 5 packages in 12ms + +``` + +See the [scripts documentation](https://docs.astral.sh/uv/guides/scripts/) to get started. + +### Tools uv executes and installs command-line tools provided by Python packages, similar to `pipx`. @@ -154,7 +185,7 @@ ruff 0.5.0 See the [tools documentation](https://docs.astral.sh/uv/guides/tools/) to get started. -### Python management +### Python versions uv installs Python and allows quickly switching between versions. @@ -196,30 +227,6 @@ Pinned `.python-version` to `3.11` See the [Python installation documentation](https://docs.astral.sh/uv/guides/install-python/) to get started. -### Script support - -uv manages dependencies and environments for single-file scripts. - -Create a new script and add inline metadata declaring its dependencies: - -```console -$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py - -$ uv add --script example.py requests -Updated `example.py` -``` - -Then, run the script in an isolated virtual environment: - -```console -$ uv run example.py -Reading inline script metadata from: example.py -Installed 5 packages in 12ms - -``` - -See the [scripts documentation](https://docs.astral.sh/uv/guides/scripts/) to get started. - ### A pip-compatible interface uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands. diff --git a/docs/getting-started/features.md b/docs/getting-started/features.md index 85509ee97..ed34dd8b2 100644 --- a/docs/getting-started/features.md +++ b/docs/getting-started/features.md @@ -3,7 +3,7 @@ uv provides essential features for Python development — from installing Python and hacking on simple scripts to working on large projects that support multiple Python versions and platforms. -uv's interface can be broken down into sections, which can be used independently or together. +uv's interface can be broken down into sections, which are usable independently or together. ## Python versions diff --git a/docs/guides/index.md b/docs/guides/index.md index 4cf4b5a8c..500506ea8 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -6,6 +6,7 @@ Check out one of the core guides to get started: - [Running scripts and declaring dependencies](./scripts.md) - [Running and installing applications as tools](./tools.md) - [Creating and working on projects](./projects.md) +- [Building and publishing packages](./package.md) - [Integrate uv with other software, e.g., Docker, GitHub, PyTorch, and more](./integration/index.md) Or, explore the [concept documentation](../concepts/index.md) for comprehensive breakdown of each diff --git a/docs/guides/integration/alternative-indexes.md b/docs/guides/integration/alternative-indexes.md index b686ed5a9..c4ff2d01d 100644 --- a/docs/guides/integration/alternative-indexes.md +++ b/docs/guides/integration/alternative-indexes.md @@ -162,7 +162,7 @@ export UV_EXTRA_INDEX_URL="https://aws:${AWS_CODEARTIFACT_TOKEN}@${AWS_DOMAIN}-$ ### Publishing packages If you also want to publish your own packages to AWS CodeArtifact, you can use `uv publish` as -described in the [publishing guide](../publish.md). You will need to set `UV_PUBLISH_URL` separately +described in the [publishing guide](../package.md). You will need to set `UV_PUBLISH_URL` separately from the credentials: ```bash diff --git a/docs/guides/publish.md b/docs/guides/package.md similarity index 98% rename from docs/guides/publish.md rename to docs/guides/package.md index 9e0fb114d..a3b9b6c5c 100644 --- a/docs/guides/publish.md +++ b/docs/guides/package.md @@ -1,9 +1,9 @@ --- -title: Publishing a package +title: Building and publishing a package description: A guide to using uv to build and publish Python packages to a package index, like PyPI. --- -# Publishing a package +# Building and publishing a package uv supports building Python packages into source and binary distributions via `uv build` and uploading them to a registry with `uv publish`. diff --git a/docs/guides/projects.md b/docs/guides/projects.md index aff63e72b..35fae50ca 100644 --- a/docs/guides/projects.md +++ b/docs/guides/projects.md @@ -232,4 +232,4 @@ To learn more about working on projects with uv, see the [projects concept](../concepts/projects/index.md) page and the [command reference](../reference/cli.md#uv). -Or, read on to learn how to [publish your project as a package](./publish.md). +Or, read on to learn how to [build and publish your project to a package index](./package.md). diff --git a/docs/index.md b/docs/index.md index ac114faeb..2d6b7c82d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,12 +19,12 @@ An extremely fast Python package and project manager, written in Rust. - 🚀 A single tool to replace `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `twine`, `virtualenv`, and more. - ⚡️ [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip`. -- 🐍 [Installs and manages](#python-management) Python versions. -- 🛠️ [Runs and installs](#tool-management) Python applications. +- 🗂️ Provides [comprehensive project management](#project), with a + [universal lockfile](./concepts/projects/layout.md#the-lockfile). - ❇️ [Runs scripts](#script-support), with support for [inline dependency metadata](./guides/scripts.md#declaring-script-dependencies). -- 🗂️ Provides [comprehensive project management](#project-management), with a - [universal lockfile](./concepts/projects/layout.md#the-lockfile). +- 🐍 [Installs and manages](#python-versions) Python versions. +- 🛠️ [Runs and installs](#tool) tools published as Python packages. - 🔩 Includes a [pip-compatible interface](#the-pip-interface) for a performance boost with a familiar CLI. - 🏢 Supports Cargo-style [workspaces](./concepts/projects/workspaces.md) for scalable projects. @@ -35,7 +35,7 @@ An extremely fast Python package and project manager, written in Rust. uv is backed by [Astral](https://astral.sh), the creators of [Ruff](https://github.com/astral-sh/ruff). -## Getting started +## Installation Install uv with our official standalone installer: @@ -58,7 +58,7 @@ Then, check out the [first steps](./getting-started/first-steps.md) or read on f uv may also be installed with pip, Homebrew, and more. See all of the methods on the [installation page](./getting-started/installation.md). -## Project management +## Projects uv manages project dependencies and environments, with support for lockfiles, workspaces, and more, similar to `rye` or `poetry`: @@ -80,14 +80,45 @@ Installed 2 packages in 1ms $ uv run ruff check All checks passed! + +$ uv lock +Resolved 2 packages in 0.33ms + +$ uv sync +Resolved 2 packages in 0.70ms +Audited 1 package in 0.02ms ``` See the [project guide](./guides/projects.md) to get started. uv also supports building and publishing projects, even if they're not managed with uv. See the -[publish guide](./guides/publish.md) to learn more. +[packaging guide](./guides/package.md) to learn more. -## Tool management +## Scripts + +uv manages dependencies and environments for single-file scripts. + +Create a new script and add inline metadata declaring its dependencies: + +```console +$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py + +$ uv add --script example.py requests +Updated `example.py` +``` + +Then, run the script in an isolated virtual environment: + +```console +$ uv run example.py +Reading inline script metadata from: example.py +Installed 5 packages in 12ms + +``` + +See the [scripts guide](./guides/scripts.md) to get started. + +## Tools uv executes and installs command-line tools provided by Python packages, similar to `pipx`. @@ -125,7 +156,7 @@ ruff 0.5.4 See the [tools guide](./guides/tools.md) to get started. -## Python management +## Python versions uv installs Python and allows quickly switching between versions. @@ -166,30 +197,6 @@ Pinned `.python-version` to `3.11` See the [installing Python guide](./guides/install-python.md) to get started. -## Script support - -uv manages dependencies and environments for single-file scripts. - -Create a new script and add inline metadata declaring its dependencies: - -```console -$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py - -$ uv add --script example.py requests -Updated `example.py` -``` - -Then, run the script in an isolated virtual environment: - -```console -$ uv run example.py -Reading inline script metadata from: example.py -Installed 5 packages in 12ms - -``` - -See the [scripts guide](./guides/scripts.md) to get started. - ## The pip interface uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands. diff --git a/mkdocs.template.yml b/mkdocs.template.yml index 3f5003366..fbaf3a75f 100644 --- a/mkdocs.template.yml +++ b/mkdocs.template.yml @@ -68,6 +68,7 @@ plugins: # Note that redirecting an anchor, e.g., `concepts/projects/#managing-dependencies` must be done # client-side and is implemented in `extra.js` instead. redirect_maps: + "guides/publish.md": "guides/package.md" "concepts/workspaces.md": "concepts/projects/workspaces.md" "concepts/dependencies.md": "concepts/projects/dependencies.md" "reference/versioning.md": "reference/policies/versioning.md" @@ -103,7 +104,7 @@ nav: - Running scripts: guides/scripts.md - Using tools: guides/tools.md - Working on projects: guides/projects.md - - Publishing packages: guides/publish.md + - Publishing packages: guides/package.md - Integrations: - guides/integration/index.md - Docker: guides/integration/docker.md @@ -166,4 +167,3 @@ validation: omitted_files: warn absolute_links: warn unrecognized_links: warn - anchors: warn