mirror of https://github.com/astral-sh/uv
Bundle of docs changes (#5426)
This commit is contained in:
Zanie Blue
GitHub
parent
ac81036aa9
commit
3581e27cdf
|
|
@ -3,101 +3,94 @@
|
|||
|
||||
uv supports the full Python development experience — from installing Python and hacking on simple scripts to working on large projects that support multiple Python versions and platforms.
|
||||
|
||||
uv's commands can be broken down into sections of discrete features which can be used independently.
|
||||
uv's commands can be broken down into sections of discrete features, which can be used independently.
|
||||
|
||||
## Python version management
|
||||
## Python versions
|
||||
|
||||
Installing and managing Python itself.
|
||||
|
||||
- `uv python install`
|
||||
- `uv python list`
|
||||
- `uv python find`
|
||||
- `uv python pin`
|
||||
- `uv python uninstall`
|
||||
- `uv python install`: Install Python versions.
|
||||
- `uv python list`: View available Python versions.
|
||||
- `uv python find`: Find an installed Python version.
|
||||
- `uv python pin`: Pin the current project to use a specific Python version.
|
||||
- `uv python uninstall`: Uninstall a Python version.
|
||||
|
||||
See the [guide on installing Python](./guides/install-python.md) to get started.
|
||||
|
||||
## Running scripts
|
||||
## Scripts
|
||||
|
||||
Executing standalone Python scripts, e.g., `example.py`.
|
||||
|
||||
- `uv run`
|
||||
- `uv run`: Run a script.
|
||||
|
||||
See the [guide on running scripts](./guides/scripts.md) to get started.
|
||||
|
||||
## Project management
|
||||
## Projects
|
||||
|
||||
Creating and working on Python projects, i.e., with a `pyproject.toml`.
|
||||
|
||||
- `uv init`
|
||||
- `uv add`
|
||||
- `uv remove`
|
||||
- `uv sync`
|
||||
- `uv lock`
|
||||
- `uv run`
|
||||
- `uv tree`
|
||||
- `uv init`: Create a new Python project.
|
||||
- `uv add`: Add a dependency to the project.
|
||||
- `uv remove`: Remove a dependency from the project.
|
||||
- `uv sync`: Sync the project's dependencies with the environment.
|
||||
- `uv lock`: Create a lockfile for the project's dependencies.
|
||||
- `uv run`: Run a command in the project environment.
|
||||
- `uv tree`: View the dependency tree for the project.
|
||||
|
||||
See the [guide on projects](./guides/projects.md) to get started.
|
||||
|
||||
## Tool installation
|
||||
## Tools
|
||||
|
||||
Running and installing tools published to Python package indexes, e.g., `ruff` or `black`.
|
||||
|
||||
- `uvx` / `uv tool run`
|
||||
- `uv tool install`
|
||||
- `uv tool uninstall`
|
||||
- `uv tool list`
|
||||
- `uv tool update-shell`
|
||||
- `uvx` / `uv tool run`: Run a tool in a temporary environment.
|
||||
- `uv tool install`: Install a tool user-wide.
|
||||
- `uv tool uninstall`: Uninstall a tool.
|
||||
- `uv tool list`: List installed tools.
|
||||
- `uv tool update-shell`: Update the shell to include tool executables.
|
||||
|
||||
See the [guide on tools](./guides/tools.md) to get started.
|
||||
|
||||
## Low-level commands
|
||||
## Low-level
|
||||
|
||||
Manually managing environments and packages — intended to be used in legacy workflows or cases where the high-level commands do not provide enough control.
|
||||
|
||||
Creating virtual environments (replacing `venv` and `virtualenv`):
|
||||
|
||||
- `uv venv`
|
||||
- `uv venv`: Create a new virtual environment.
|
||||
|
||||
See the documentation on [using environments](./pip/environments.md) for details.
|
||||
|
||||
Managing packages in an environment (replacing [`pip`](https://github.com/pypa/pip)):
|
||||
Managing packages in an environment (replacing [`pip`](https://github.com/pypa/pip) and [`pipdeptree`](https://github.com/tox-dev/pipdeptree)):
|
||||
|
||||
- `uv pip install`
|
||||
- `uv pip show`
|
||||
- `uv pip freeze`
|
||||
- `uv pip check`
|
||||
- `uv pip list`
|
||||
- `uv pip uninstall`
|
||||
- `uv pip install`: Install packages into the current environment.
|
||||
- `uv pip show`: Show details about an installed package.
|
||||
- `uv pip freeze`: List installed packages and their versions.
|
||||
- `uv pip check`: Check that the current environment has compatible packages.
|
||||
- `uv pip list`: List installed packages.
|
||||
- `uv pip uninstall`: Uninstall packages.
|
||||
- `uv pip tree`: View the dependency tree for the environment.
|
||||
|
||||
See the documentation on [managing packages](./pip/packages.md) for details.
|
||||
|
||||
Locking packages in an environment (replacing [`pip-tools`](https://github.com/jazzband/pip-tools)):
|
||||
|
||||
- `uv pip compile`
|
||||
- `uv pip sync`
|
||||
- `uv pip compile`: Compile requirements into a lockfile.
|
||||
- `uv pip sync`: Sync an environment with a lockfile.
|
||||
|
||||
See the documentation on [locking environments](./pip/compile.md) for details.
|
||||
|
||||
Viewing package dependencies in an environment (replacing [`pipdeptree`](https://github.com/tox-dev/pipdeptree)):
|
||||
|
||||
- `uv pip tree`
|
||||
|
||||
!!! important
|
||||
|
||||
These commands do not exactly implement the interfaces and behavior of the tools they are based on. The further you stray from common workflows, the more likely you are to encounter differences. Consult the [pip-compatibility guide](./pip/compatibility.md) for details.
|
||||
|
||||
## Internal commands
|
||||
## Internal
|
||||
|
||||
Managing and inspecting uv's state, such as the cache, storage directories, or performing a self-update:
|
||||
|
||||
- `uv cache clean`
|
||||
- `uv cache prune`
|
||||
- `uv cache dir`
|
||||
- `uv tool dir`
|
||||
- `uv python dir`
|
||||
- `uv self update`
|
||||
|
||||
## Next steps
|
||||
|
||||
Check out the [documentation overview](./overview.md) for a list of guides and concepts.
|
||||
- `uv cache clean`: Remove cache entries.
|
||||
- `uv cache prune`: Remove outdated cache entries.
|
||||
- `uv cache dir`: Show the uv cache directory path.
|
||||
- `uv tool dir`: Show the uv tool directory path.
|
||||
- `uv python dir`: Show the uv installed Python versions path.
|
||||
- `uv self update`: Update uv to the latest version.
|
||||
|
|
|
|||
|
|
@ -56,4 +56,4 @@ When using the long help menu, uv will attempt to use `less` or `more` to "page"
|
|||
|
||||
## Next steps
|
||||
|
||||
Now that you've confirmed uv is installed and know how to get help, check out the [feature overview](./features.md) to start using uv.
|
||||
Now that you've confirmed uv is installed and know how to get help, check out an [overview of features](./features.md) or jump straight into the [guides](./guides/overview.md) to start using uv.
|
||||
|
|
|
|||
|
|
@ -2,6 +2,10 @@
|
|||
|
||||
If Python is already installed on your system, uv will [detect and use](#using-an-existing-python-installation) it without configuration. However, uv can also install and manage Python versions for you.
|
||||
|
||||
!!! tip
|
||||
|
||||
uv will [automatically fetch Python versions](#automatic-python-downloads) as needed — you don't need to install Python to get started.
|
||||
|
||||
To install the latest Python version:
|
||||
|
||||
```console
|
||||
|
|
@ -59,10 +63,10 @@ Note that Python does not need to be explicitly installed to use uv. By default,
|
|||
$ uv run --python 3.12 python -c 'print("hello world")'
|
||||
```
|
||||
|
||||
Even if a specific Python version is not requested, uv will download the latest version on demand. For example, the following will create a new virtual environment and download a managed Python version if one hasn't been installed yet:
|
||||
Even if a specific Python version is not requested, uv will download the latest version on demand. For example, the following will create a new virtual environment and download a managed Python version if Python is not found:
|
||||
|
||||
```console
|
||||
$ uv venv --python-preference only-managed
|
||||
$ uv venv
|
||||
```
|
||||
|
||||
<!-- TODO(zanieb): Restore when Python shim management is added
|
||||
|
|
|
|||
|
|
@ -0,0 +1,26 @@
|
|||
# Overview
|
||||
|
||||
Check out one of the core guides to get started:
|
||||
|
||||
- [Installing Python versions](./install-python.md)
|
||||
- [Running scripts and declaring dependencies](./scripts.md)
|
||||
- [Running and installing applications as tools](./tools.md)
|
||||
- [Creating and working on projects](./projects.md)
|
||||
|
||||
Learn how to integrate uv with other software:
|
||||
|
||||
- [Using in Docker images](./integration/docker.md)
|
||||
- [Using with pre-commit](./integration/pre-commit.md)
|
||||
- [Using in GitHub Actions](./integration/github.md)
|
||||
- [Using with commercial package indexes](./integration/commercial-indexes.md)
|
||||
|
||||
Or, explore the concept documentation for comprehensive breakdown of each feature:
|
||||
|
||||
- [Projects](../projects.md)
|
||||
- [Dependencies](../dependencies.md)
|
||||
- [Workspaces](../workspaces.md)
|
||||
- [Tools](../tools.md)
|
||||
- [Python versions](../python-versions.md)
|
||||
- [Resolution](../resolution.md)
|
||||
- [Caching](../cache.md)
|
||||
- [Authentication](../configuration/authentication.md)
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# Working on projects
|
||||
|
||||
uv is capable of managing Python projects following the `pyproject.toml` standard.
|
||||
uv is capable of managing Python projects using a `pyproject.toml` with a `[project]` metadata table.
|
||||
|
||||
## Creating a new project
|
||||
|
||||
|
|
@ -69,6 +69,10 @@ such as it's description or license. You can edit this file manually, or use
|
|||
commands like `uv add` and `uv remove` to manage your project through the
|
||||
CLI.
|
||||
|
||||
!!! tip
|
||||
|
||||
See the official [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for more details on getting started with the `pyproject.toml` format.
|
||||
|
||||
### `.venv`
|
||||
|
||||
The `.venv` folder contains your project's virtual environment, a Python
|
||||
|
|
@ -102,9 +106,14 @@ virtual environment before executing a command:
|
|||
|
||||
```console
|
||||
$ uv sync
|
||||
$ source .venv/bin/active
|
||||
$ python my_script.py
|
||||
```
|
||||
|
||||
!!! note
|
||||
|
||||
The virtual environment must be active to run scripts and commands in the project without `uv run`. Virtual environment activation differs per shell and platform.
|
||||
|
||||
## Managing dependencies
|
||||
|
||||
You can add dependencies to your `pyproject.toml` with the `uv add` command.
|
||||
|
|
|
|||
|
|
@ -102,7 +102,7 @@ Note that if `uv run` is used in a _project_, these dependencies will be include
|
|||
|
||||
Python recently added a standard format for [inline script metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/#inline-script-metadata). This allows the dependencies for a script to be declared in the script itself.
|
||||
|
||||
To use inline script metadata, include a `script` section at the top of the script:
|
||||
To use inline script metadata, include a `script` section at the top of the script and declare the dependencies using TOML:
|
||||
|
||||
```python title="example.py"
|
||||
# /// script
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Using tools
|
||||
|
||||
Many Python packages provide command-line interfaces which are useful as standalone tools. uv has specialized support for easily invoking and installing tools.
|
||||
Many Python packages provide applications that can be used as tools. uv has specialized support for easily invoking and installing tools.
|
||||
|
||||
## Using `uvx`
|
||||
|
||||
|
|
@ -90,7 +90,7 @@ $ uvx --with mkdocs-material mkdocs --help
|
|||
|
||||
## Installing tools
|
||||
|
||||
If a tool is used often, it can be useful to install it to a persistent environment instead of invoking `uvx` repeatedly.
|
||||
If a tool is used often, it can be useful to install it to a persistent environment and add it to the `PATH` instead of invoking `uvx` repeatedly.
|
||||
|
||||
To install `ruff`:
|
||||
|
||||
|
|
|
|||
|
|
@ -23,30 +23,30 @@ An extremely fast Python package and project manager, written in Rust.
|
|||
## Highlights
|
||||
|
||||
- 🐍 [Installs and manages](./guides/install-python.md) Python versions.
|
||||
- 🛠️ [Executes and installs](./guides/tools.md) commands provided by Python packages.
|
||||
- ❇️ [Runs scripts](./guides/scripts.md) with [inline dependency metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/#inline-script-metadata).
|
||||
- 🗂️ Provides [comprehensive project management](./guides/projects.md), with a multi-platform lock file.
|
||||
- 🏢 Supports Cargo-style [workspaces](./workspaces.md) for large projects.
|
||||
- 🛠️ [Runs and installs](./guides/tools.md) Python applications.
|
||||
- ❇️ [Runs scripts](./guides/scripts.md), with support for [inline dependency metadata](./guides/scripts.md#declaring-script-dependencies).
|
||||
- 🗂️ Provides [comprehensive project management](./guides/projects.md), with a [universal lockfile](./projects.md#lock-file).
|
||||
- 🏢 Supports Cargo-style [workspaces](./workspaces.md) for scalable projects.
|
||||
- 🚀 A replacement for `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `virtualenv`, and more.
|
||||
- ⚡️ [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip`
|
||||
and `pip-tools` (`pip-compile` and `pip-sync`).
|
||||
- 🧪 Tested at-scale against the top 10,000 PyPI packages.
|
||||
- 💾 Disk-space efficient, with a [global cache](./cache.md) for dependency deduplication.
|
||||
- ⁉️ Best-in-class error messages with a conflict-tracking resolver.
|
||||
- ⏬ A static binary that can be installed without Rust or Python via `curl` or `pip`.
|
||||
- 🖥️ Support for macOS, Linux, and Windows.
|
||||
- ⏬ Installable without Rust or Python via `curl` or `pip`.
|
||||
- 🖥️ Supports macOS, Linux, and Windows.
|
||||
|
||||
uv is backed by [Astral](https://astral.sh), the creators of [Ruff](https://github.com/astral-sh/ruff).
|
||||
|
||||
## Getting started
|
||||
|
||||
Install uv with our official standalone installer:
|
||||
Install uv with our official standalone installer, on macOS and Linux:
|
||||
|
||||
```bash
|
||||
# On macOS and Linux.
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
```
|
||||
|
||||
# On Windows.
|
||||
Or, on Windows:
|
||||
|
||||
```bash
|
||||
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
|
||||
```
|
||||
|
||||
|
|
@ -54,7 +54,7 @@ Then, check out the [first steps](./first-steps.md), see more [installation meth
|
|||
|
||||
## Project management
|
||||
|
||||
uv can manage project dependencies and environments:
|
||||
uv manages project dependencies and environments:
|
||||
|
||||
```console
|
||||
$ uv init example
|
||||
|
|
@ -71,7 +71,7 @@ Installed 2 packages in 1ms
|
|||
+ example==0.1.0 (from file:///home/user/example)
|
||||
+ ruff==0.5.4
|
||||
|
||||
$ uv run -- ruff check
|
||||
$ uv run ruff check
|
||||
All checks passed!
|
||||
```
|
||||
|
||||
|
|
@ -79,7 +79,7 @@ See the [project guide](./guides/projects.md) to get started.
|
|||
|
||||
## Tool management
|
||||
|
||||
uv provides an interface for executing and installing command-line tools provided by Python packages, similar to `pipx`.
|
||||
uv executes and installs command-line tools provided by Python packages, similar to `pipx`.
|
||||
|
||||
Run a tool in an ephemeral environment with `uvx`:
|
||||
|
||||
|
|
@ -117,7 +117,7 @@ See the [tools guide](./guides/tools.md) to get started.
|
|||
|
||||
## Python management
|
||||
|
||||
uv supports installing Python and managing multiple Python versions.
|
||||
uv installs Python and allows quickly switching between Python versions.
|
||||
|
||||
Install the Python versions your project requires:
|
||||
|
||||
|
|
@ -137,8 +137,22 @@ Or, fetch Python versions on demand:
|
|||
|
||||
```console
|
||||
$ uv venv --python 3.12.0
|
||||
Using Python 3.12.0
|
||||
Creating virtualenv at: .venv
|
||||
Activate with: source .venv/bin/activate
|
||||
|
||||
$ uv run --python pypy@3.8 -- python --version
|
||||
Python 3.8.16 (a9dbdca6fc3286b0addd2240f11d97d8e8de187a, Dec 29 2022, 11:45:30)
|
||||
[PyPy 7.3.11 with GCC Apple LLVM 13.1.6 (clang-1316.0.21.2.5)] on darwin
|
||||
Type "help", "copyright", "credits" or "license" for more information.
|
||||
>>>>
|
||||
```
|
||||
|
||||
Use a specific Python version in the current directory:
|
||||
|
||||
```
|
||||
$ uv python pin pypy@3.11
|
||||
Pinned `.python-version` to `pypy@3.11`
|
||||
```
|
||||
|
||||
See the [installing Python guide](./guides/install-python.md) to get started.
|
||||
|
|
@ -161,7 +175,7 @@ Create a virtual environment:
|
|||
|
||||
```console
|
||||
$ uv venv
|
||||
Using Python 3.12.3 interpreter at: /opt/homebrew/opt/python@3.12/bin/python3.12
|
||||
Using Python 3.12.3
|
||||
Creating virtualenv at: .venv
|
||||
Activate with: source .venv/bin/activate
|
||||
```
|
||||
|
|
@ -182,4 +196,4 @@ See the [uv pip documentation](./pip/environments.md) to get started.
|
|||
|
||||
## Next steps
|
||||
|
||||
See the [documentation overview](./overview.md) to learn more about uv.
|
||||
See the [first steps](./first-steps.md) or jump straight into the [guides](./guides/overview.md) to start using uv.
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
|
|||
|
||||
uv is installed to `~/.cargo/bin`.
|
||||
|
||||
!!! note
|
||||
!!! tip
|
||||
|
||||
The installation script may be inspected with:
|
||||
|
||||
|
|
@ -40,13 +40,13 @@ curl -LsSf https://astral.sh/uv/0.2.11/install.sh | sh
|
|||
powershell -c "irm https://astral.sh/uv/0.2.11/install.ps1 | iex"
|
||||
```
|
||||
|
||||
When the standalone installer is used, uv can upgrade itself.
|
||||
When the standalone installer is used, uv can upgrade itself:
|
||||
|
||||
```bash
|
||||
uv self update
|
||||
```
|
||||
|
||||
When all other installers are used, self updates are disabled. Use the package manager's upgrade method instead.
|
||||
When another installation method is used, self updates are disabled. Use the package manager's upgrade method instead.
|
||||
|
||||
## PyPI
|
||||
|
||||
|
|
|
|||
|
|
@ -1,23 +0,0 @@
|
|||
# Overview
|
||||
|
||||
Check out one of our guides to get started:
|
||||
|
||||
- [Installing Python](./guides/install-python.md)
|
||||
- [Running scripts](./guides/scripts.md)
|
||||
- [Using tools](./guides/tools.md)
|
||||
- [Working on projects](./guides/projects.md)
|
||||
- [Using in Docker](./guides/integration/docker.md)
|
||||
- [Using with pre-commit](./guides/integration/pre-commit.md)
|
||||
- [Using in GitHub Actions](./guides/integration/github.md)
|
||||
- [Using with commercial package indexes](./guides/integration/commercial-indexes.md)
|
||||
|
||||
Or, explore the concept documentation for comprehensive breakdown of each feature:
|
||||
|
||||
- [Projects](./projects.md)
|
||||
- [Dependencies](./dependencies.md)
|
||||
- [Workspaces](./workspaces.md)
|
||||
- [Tools](./tools.md)
|
||||
- [Python versions](./python-versions.md)
|
||||
- [Resolution](./resolution.md)
|
||||
- [Caching](./cache.md)
|
||||
- [Authentication](./configuration/authentication.md)
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
Python projects are help manage Python applications spanning multiple files.
|
||||
|
||||
!!! note
|
||||
!!! tip
|
||||
|
||||
Looking for an introduction to creating a project with uv? See the [projects guide](./guides/projects.md) first.
|
||||
|
||||
|
|
@ -32,7 +32,9 @@ This Python version requirement determines what syntax is valid in the project a
|
|||
|
||||
The `pyproject.toml` also lists dependencies of the project. uv supports modifying the standard dependency list from the command line with `uv add` and `uv remove`. uv also supports [extended package sources](./dependencies.md) for advanced users.
|
||||
|
||||
See the official [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for more details on getting started with a `pyproject.toml`.
|
||||
!!! tip
|
||||
|
||||
See the official [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for more details on getting started with a `pyproject.toml`.
|
||||
|
||||
## Project environments
|
||||
|
||||
|
|
|
|||
|
|
@ -74,8 +74,8 @@ nav:
|
|||
- Installation: installation.md
|
||||
- First steps: first-steps.md
|
||||
- Features: features.md
|
||||
- Overview: overview.md
|
||||
- Guides:
|
||||
- Overview: guides/overview.md
|
||||
- Installing Python: guides/install-python.md
|
||||
- Running scripts: guides/scripts.md
|
||||
- Using tools: guides/tools.md
|
||||
|
|
|
|||
Loading…
Reference in New Issue