mirrors/uv
1
0
Fork 0
mirror of https://github.com/astral-sh/uv.git synced 2025-07-07 21:35:00 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Improvements to the documentation (#5718)

Browse source
This commit is contained in:
Zanie Blue 2024-08-03 08:41:33 -05:00 • committed by GitHub
parent 00981732a6
commit 44a6dbfa53
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
19 changed files with 275 additions and 209 deletions
Download patch file Download diff file Expand all files Collapse all files

4
CONTRIBUTING.md
View file

@ -78,8 +78,8 @@ system
["nvidia-pyindex" on PyPI](https://pypi.org/project/nvidia-pyindex/)), which can even occur when
just resolving requirements. To prevent this, there's a Docker container you can run commands in:
```bash
docker buildx build -t uv-builder -f builder.dockerfile --load .
```console
$ docker buildx build -t uv-builder -f builder.dockerfile --load .
# Build for musl to avoid glibc errors, might not be required with your OS version
cargo build --target x86_64-unknown-linux-musl --profile profiling
docker run --rm -it -v $(pwd):/app uv-builder /app/target/x86_64-unknown-linux-musl/profiling/uv-dev resolve-many --cache-dir /app/cache-docker /app/scripts/popular_packages/pypi_10k_most_dependents.txt

3
STYLE.md
View file

@ -84,7 +84,8 @@ The documentation is divided into:
1. All code blocks should have a language marker.
1. When using `console` syntax, use `$` to indicate commands — everything else is output.
1. Do not use the `bash` syntax when displaying command output.
1. Never use the `bash` syntax when displaying command output.
1. Prefer `console` with `$` prefixed commands over `bash`.
1. Command output should rarely be included — it's hard to keep up to date.
1. Use `title` for example files, e.g., `pyproject.toml`, `Dockerfile`, or `example.py`.

4
docs/concepts/projects.md
View file

@ -152,10 +152,10 @@ command.
The given command can be provided by the project environment or exist outside of it, e.g.:
```console
# Presuming the project provides `example-cli`
$ # Presuming the project provides `example-cli`
$ uv run example-cli foo
# Running a `bash` script that requires the project to be available
$ # Running a `bash` script that requires the project to be available
$ uv run bash scripts/foo.sh
```

45
docs/concepts/python-versions.md
View file

@ -22,8 +22,8 @@ installations and all other Python installations as _system_ Python installation
A specific Python version can be requested with the `--python` flag in most uv commands. For
example, when creating a virtual environment:
```bash
uv venv --python 3.11.6
```console
$ uv venv --python 3.11.6
```
uv will ensure that Python 3.11.6 is available — downloading and installing it if necessary — then
@ -60,28 +60,37 @@ uv bundles a list of downloadable CPython and PyPy distributions for macOS, Linu
To install a Python version at a specific version:
```bash
uv python install 3.12.3
```console
$ uv python install 3.12.3
```
To install the latest patch version:
```bash
uv python install 3.12
```console
$ uv python install 3.12
```
To install a version that satisfies constraints:
```bash
uv python install '>=3.8,<3.10'
```console
$ uv python install '>=3.8,<3.10'
```
To install multiple versions:
```bash
uv python install 3.9 3.10 3.11
```console
$ uv python install 3.9 3.10 3.11
```
To install a specific implementation:
```console
$ uv python install pypy
```
All of the [Python version request](#requesting-a-version) formats are supported except those that
are used for requesting local interpreters such as a file path.
## Project Python versions
By default `uv python install` will verify that a managed Python version is installed or install the
@ -101,28 +110,28 @@ invocations.
To list installed and available Python versions:
```bash
uv python list
```console
$ uv python list
```
By default, downloads for other platforms and old patch versions are hidden.
To view all versions:
```bash
uv python list --all-versions
```console
$ uv python list --all-versions
```
To view Python versions for other platforms:
```bash
uv python list --all-platforms
```console
$ uv python list --all-platforms
```
To exclude downloads and only show installed Python versions:
```bash
uv python list --only-installed
```console
$ uv python list --only-installed
```
## Discovery of Python versions

7
docs/features.md
View file

@ -1,10 +1,9 @@
# Features
uv supports the full Python development experience — from installing Python and hacking on simple
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 commands can be broken down into sections of discrete features, which can be used
independently.
uv's interface can be broken down into sections, which can be used independently or together.
## Python versions
@ -87,7 +86,7 @@ See the documentation on [locking environments](./pip/compile.md) for details.
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
## Utility
Managing and inspecting uv's state, such as the cache, storage directories, or performing a
self-update:

10
docs/first-steps.md
View file

@ -2,11 +2,16 @@
uv only provides a command-line interface and must be used from a terminal.
After [installing uv](./installation.md), you can check that uv is installed by running the `uv`
After [installing uv](./installation.md), you can check that uv is available by running the `uv`
command:
```console
$ uv
An extremely fast Python package manager.
Usage: uv [OPTIONS] <COMMAND>
...
```
You should see a help menu listing the available commands.
@ -63,5 +68,4 @@ $ uv pip --version # Can be used with a subcommand
## Next steps
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/index.md) to start
using uv.
[overview of features](./features.md) or jump to the [guides](./guides/index.md) to start using uv.

46
docs/guides/install-python.md
View file

@ -8,14 +8,18 @@ also install and manage Python versions for you.
uv will [automatically fetch Python versions](#automatic-python-downloads) as needed — you don't need to install Python to get started.
<!-- TODO(zanieb): I don't love this heading. -->
## Getting started
To install the latest Python version:
```console
$ uv python install
```
This will install a uv managed Python version even if there is already a Python installation on your
system.
This will install a uv-managed Python version even if there is already a Python installation on your
system. If you've previously installed Python with uv, a new version will not be installed.
!!! note
@ -35,6 +39,13 @@ To prevent uv from managing Python system-wide, provide the `--no-shim` option d
Once Python is installed, it will be used by `uv` commands automatically.
!!! important
When Python is installed by uv, it will not be available globally (i.e. via the `python` command).
Support for this feature is planned for a future release. In the meantime, use
[`uv run`](../guides/scripts.md#using-different-python-versions) or
[create and activate a virtual environment](../pip/environments.md) to use `python` directly.
## Installing a specific version
To install a specific Python version:
@ -43,6 +54,18 @@ To install a specific Python version:
$ uv python install 3.12
```
To install multiple Python versions:
```console
$ uv python install 3.11 3.12
```
To install an alternative Python implementation, e.g. PyPy:
```
$ uv python install pypy@3.12
```
See the [`python install`](../concepts/python-versions.md#installing-a-python-version) documentation
for more details.
@ -77,17 +100,28 @@ version if Python is not found:
$ uv venv
```
!!! tip
Automatic Python downloads can be [easily disabled](../concepts/python-versions.md#disabling-automatic-python-downloads) if you want more control over when Python is downloaded.
<!-- TODO(zanieb): Restore when Python shim management is added
Note that when an automatic Python installation occurs, the `python` command will not be added to the shell. Use `uv python install-shim` to ensure the `python` shim is installed.
-->
## Using an existing Python installation
uv will also use an existing Python installation if already present on your system. There is no
configuration necessary for this behavior: uv will use the system Python if it satisfies the
requirements of the command invocation. See the
[Python discovery](../concepts/python-versions.md#discovery-order) documentation for details.
uv will use existing Python installations if present on your system. There is no configuration
necessary for this behavior: uv will use the system Python if it satisfies the requirements of the
command invocation. See the [Python discovery](../concepts/python-versions.md#discovery-order)
documentation for details.
To force uv to use the system Python, provide the `--python-preference only-system` option. See the
[Python version preference](../concepts/python-versions.md#adjusting-python-version-preferences)
documentation for more details.
## Next steps
To learn more about `uv python`, see the [Python version concept](../concepts/python-versions.md)
page and the [command reference](../reference/cli.md#uv-python).
Or, read on to learn how to [run scripts](./scripts.md) and invoke Python with uv.

21
docs/guides/integration/alternative-indexes.md
View file

@ -19,9 +19,10 @@ If there is a PAT available (eg
credentials can be provided via the "Basic" HTTP authentication scheme. Include the PAT in the
password field of the URL. A username must be included as well, but can be any string.
```bash
# With the token stored in the `ADO_PAT` environment variable
export UV_EXTRA_INDEX_URL=https://dummy:$ADO_PAT@pkgs.dev.azure.com/{organisation}/{project}/_packaging/{feedName}/pypi/simple/
For example, with the token stored in the `$ADO_PAT` environment variable, set the index URL with:
```console
$ export UV_EXTRA_INDEX_URL=https://dummy:$ADO_PAT@pkgs.dev.azure.com/{organisation}/{project}/_packaging/{feedName}/pypi/simple/
```
### Using `keyring`
@ -44,15 +45,15 @@ The `keyring` executable must be in the `PATH`, i.e., installed globally or in t
environment. The `keyring` CLI requires a username in the URL, so the index URL must include the
default username `VssSessionToken`.
```bash
# Pre-install keyring and the Artifacts plugin from the public PyPI
uv tool install keyring --with artifacts-keyring
```console
$ # Pre-install keyring and the Artifacts plugin from the public PyPI
$ uv tool install keyring --with artifacts-keyring
# Enable keyring authentication
export UV_KEYRING_PROVIDER=subprocess
$ # Enable keyring authentication
$ export UV_KEYRING_PROVIDER=subprocess
# Configure the index URL with the username
export UV_EXTRA_INDEX_URL=https://VssSessionToken@pkgs.dev.azure.com/{organisation}/{project}/_packaging/{feedName}/pypi/simple/
$ # Configure the index URL with the username
$ export UV_EXTRA_INDEX_URL=https://VssSessionToken@pkgs.dev.azure.com/{organisation}/{project}/_packaging/{feedName}/pypi/simple/
```
## Other indexes

4
docs/guides/integration/docker.md
View file

@ -5,8 +5,8 @@
A Docker image is published with a built version of uv available. To run a uv command in a
container:
```bash
docker run ghcr.io/astral-sh/uv --help
```console
$ docker run ghcr.io/astral-sh/uv --help
```
## Installing uv

10
docs/guides/projects.md
View file

@ -106,10 +106,10 @@ $ uv add requests
You can also specify version constraints or alternative sources:
```console
# Specify a version constraint
$ # Specify a version constraint
$ uv add 'requests==2.31.0'
# Add a git dependency
$ # Add a git dependency
$ uv add requests --git https://github.com/psf/requests
```
@ -166,5 +166,7 @@ See the documentation on [running commands](../concepts/projects.md#running-comm
## Next steps
See the [projects concept](../concepts/projects.md) documentation for more details about working
with projects.
To learn more about working on projects with uv, see the [Projects concept](../concepts/projects.md)
page and the [command reference](../reference/cli.md#uv).
Or, read on to learn how to [run and install tools](./tools.md) with uv.

40
docs/guides/scripts.md
View file

@ -1,8 +1,15 @@
# Running scripts
A Python script is a file intended for standalone execution, e.g., with `python <script>.py`. Using
uv to execute scripts will ensure that script dependencies are properly managed inside and outside
of projects.
uv to execute scripts ensures that script dependencies are managed without manually managing
environments.
!!! note
If you are not familiar with Python environments: every Python installation has an environment
that packages can be installed in. Typically, creating [_virtual_ environments](https://docs.python.org/3/library/venv.html) is recommended to
isolate packages required by each script. uv automatically manages virtual environments for you
and prefers a [declarative](#declaring-script-dependencies) approach to dependencies.
## Running a script without dependencies
@ -53,7 +60,7 @@ install the current project before running the script. If your script does not d
project, use the `--no-project` flag to skip this:
```console
# Note, it is important that the flag comes _before_ the script
$ # Note, it is important that the flag comes _before_ the script
$ uv run --no-project example.py
```
@ -149,7 +156,11 @@ $ uv run example.py
]
```
uv also supports Python version requirements:
!!! important
When using inline script metadata, even if `uv run` is [used in a _project_](../concepts/projects.md#running-scripts), the project's dependencies will be ignored. The `--no-project` flag is not required.
uv also respects Python version requirements:
```python title="example.py"
# /// script
@ -162,12 +173,13 @@ type Point = tuple[float, float]
print(Point)
```
uv will fetch the required Python version if it is not installed — see the documentation on
[Python versions](../concepts/python-versions.md) for more details. Note that the `dependencies`
field must be provided even if empty.
!!! note
Note that when using inline script metadata, even if `uv run` is used in a _project_, the project's
dependencies will be ignored. The `--no-project` flag is not required.
The `dependencies` field must be provided even if empty.
`uv run` will search for and use the required Python version. The Python version will download if it
is not installed — see the documentation on [Python versions](../concepts/python-versions.md) for
more details.
## Using different Python versions
@ -180,16 +192,22 @@ print(".".join(map(str, sys.version_info[:3])))
```
```console
# Use the default Python version, may differ on your machine
$ # Use the default Python version, may differ on your machine
$ uv run example.py
3.12.1
```
```console
# Use a specific Python version
$ # Use a specific Python version
$ uv run --python 3.10 example.py
3.10.13
```
See the [Python version request](../concepts/python-versions.md#requesting-a-version) documentation
for more details on requesting Python versions.
## Next steps
To learn more about `uv run`, see the [command reference](../reference/cli.md#uv-run).
Or, read on to learn how to to [work on projects](./projects.md).

4
docs/guides/tools.md
View file

@ -151,5 +151,5 @@ $ uv tool install mkdocs --with mkdocs-material
## Next steps
See the [tools concept](../concepts/tools.md) documentation for more details on how tools are
managed.
To learn more about managing tools with uv, see the [Tools concept](../concepts/projects.md) page
and the [command reference](../reference/cli.md#uv-tool).

45
docs/index.md
View file

@ -35,20 +35,22 @@ uv is backed by [Astral](https://astral.sh), the creators of
## Getting started
Install uv with our official standalone installer, on macOS and Linux:
Install uv with our official standalone installer:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```console title="macOS and Linux"
$ curl -LsSf https://astral.sh/uv/install.sh | sh
```
Or, on Windows:
```bash
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```console title="Windows"
$ powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
Then, check out the [first steps](./first-steps.md), see more
[installation methods](./installation.md), or read on for a brief overview.
Then, check out the [first steps](./first-steps.md) or read on for a brief overview.
!!! tip
uv may also be installed with pip, Homebrew, and more. See all of the methods on the
[installation page](./installation.md).
## Project management
@ -115,13 +117,12 @@ See the [tools guide](./guides/tools.md) to get started.
## Python management
uv installs Python and allows quickly switching between Python versions.
uv installs Python and allows quickly switching between versions.
Install the Python versions your project requires:
Install multiple Python versions:
```console
$ uv python install 3.10 3.11 3.12
warning: `uv python install` is experimental and may change without warning
Searching for Python versions matching: Python 3.10
Searching for Python versions matching: Python 3.11
Searching for Python versions matching: Python 3.12
@ -131,7 +132,7 @@ Installed 3 versions in 3.42s
+ cpython-3.12.4-macos-aarch64-none
```
Or, fetch Python versions on demand:
Download Python versions as needed:
```console
$ uv venv --python 3.12.0
@ -157,18 +158,16 @@ See the [installing Python guide](./guides/install-python.md) to get started.
## The pip interface
uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands with
support for a wide range of advanced `pip` features, including editable installs, Git dependencies,
direct URL dependencies, local dependencies, constraints, source distributions, HTML and JSON
indexes, and more.
uv extends these interfaces with advanced features, such as dependency version overrides,
uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands. uv
extends their interfaces with advanced features, such as dependency version overrides,
multi-platform resolutions, reproducible resolutions, alternative resolution strategies, and more.
Compile requirements into a multi-platform requirements file:
```console
$ uv pip compile docs/requirements.in --universal --output-file docs/requirements.txt
$ uv pip compile docs/requirements.in \
--universal \
--output-file docs/requirements.txt
Resolved 43 packages in 12ms
```
@ -193,9 +192,9 @@ Installed 43 packages in 208ms
...
```
See the [uv pip documentation](./pip/index.md) to get started.
See the [pip interface documentation](./pip/index.md) to get started.
## Next steps
See the [first steps](./first-steps.md) or jump straight into the [guides](./guides/index.md) to
start using uv.
See the [first steps](./first-steps.md) or jump straight to the [guides](./guides/index.md) to start
using uv.

62
docs/installation.md
View file

@ -6,48 +6,50 @@ Install uv with our standalone installers, from PyPI, or from your package manag
uv provides a standalone installer that downloads and installs uv:
```bash
# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh
```console title="macOS and Linux"
$ curl -LsSf https://astral.sh/uv/install.sh | sh
```
# On Windows.
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```console title="Windows"
$ powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
uv is installed to `~/.cargo/bin`.
!!! tip
The installation script may be inspected with:
The installation script may be inspected before use:
```bash
# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | less
```console title="macOS and Linux"
$ curl -LsSf https://astral.sh/uv/install.sh | less
```
# On Windows.
powershell -c "irm https://astral.sh/uv/install.ps1 | more"
```console title="Windows"
$ powershell -c "irm https://astral.sh/uv/install.ps1 | more"
```
Alternatively, the installer or binaries can be downloaded directly from [GitHub](#github-releases).
A specific release can be requested by including the version in the URL:
Request a specific version by including it in the URL:
```bash
# On macOS and Linux.
curl -LsSf https://astral.sh/uv/0.2.11/install.sh | sh
# On Windows.
powershell -c "irm https://astral.sh/uv/0.2.11/install.ps1 | iex"
```console title="macOS and Linux"
$ curl -LsSf https://astral.sh/uv/0.2.11/install.sh | sh
```
When the standalone installer is used, uv can upgrade itself:
```bash
uv self update
```console title="Windows"
$ powershell -c "irm https://astral.sh/uv/0.2.11/install.ps1 | iex"
```
When another installation method is used, self updates are disabled. Use the package manager's
upgrade method instead.
!!! tip
When the standalone installer is used, uv can perform self-updates:
```console
$ uv self update
```
When another installation method is used, self-updates are disabled. Use the package manager's
upgrade method instead.
## PyPI
@ -55,14 +57,14 @@ For convenience, uv is published to [PyPI](https://pypi.org/project/uv/).
If installing from PyPI, we recommend installing uv into an isolated environment, e.g., with `pipx`:
```bash
pipx install uv
```console
$ pipx install uv
```
However, `pip` can also be used:
```bash
pip install uv
```console
$ pip install uv
```
!!! note
@ -76,8 +78,8 @@ pip install uv
uv is available in the core Homebrew packages.
```bash
brew install uv
```console
$ brew install uv
```
## Docker

48
docs/pip/compile.md
View file

@ -14,8 +14,8 @@ define dependencies.
To lock dependencies declared in a `pyproject.toml`:
```bash
uv pip compile pyproject.toml -o requirements.txt
```console
$ uv pip compile pyproject.toml -o requirements.txt
```
Note by default the `uv pip compile` output is just displayed and `--output-file` / `-o` argument is
@ -23,39 +23,39 @@ needed to write to a file.
To lock dependencies declared in a `requirements.in`:
```bash
uv pip compile requirements.in -o requirements.txt
```console
$ uv pip compile requirements.in -o requirements.txt
```
To lock dependencies declared in multiple files:
```bash
uv pip compile pyproject.toml requirements-dev.in -o requirements-dev.txt`
```console
$ uv pip compile pyproject.toml requirements-dev.in -o requirements-dev.txt`
```
uv also supports legacy `setup.py` and `setup.cfg` formats. To lock dependencies declared in a
`setup.py`:
```bash
uv pip compile setup.py -o requirements.txt
```console
$ uv pip compile setup.py -o requirements.txt
```
To lock dependencies from stdin, use `-`:
```bash
echo "ruff" | uv pip compile -
```console
$ echo "ruff" | uv pip compile -
```
To lock with optional dependencies enabled, e.g., the "foo" extra:
```bash
uv pip install -r pyproject.toml --extra foo
```console
$ uv pip install -r pyproject.toml --extra foo
```
To lock with all optional dependencies enabled:
```bash
uv pip install -r pyproject.toml --all-extras
```console
$ uv pip install -r pyproject.toml --all-extras
```
Note extras are not supported with the `requirements.in` format.
@ -75,8 +75,8 @@ ruff==0.3.0
To upgrade a dependency, use the `--upgrade-package` flag:
```bash
uv pip compile - -o requirements.txt --upgrade-package ruff
```console
$ uv pip compile - -o requirements.txt --upgrade-package ruff
```
To upgrade all dependencies, there is an `--upgrade` flag.
@ -94,14 +94,14 @@ exactly matches the lockfile, use `uv pip sync` instead.
To sync an environment with a `requirements.txt` file:
```bash
uv pip sync requirements.txt
```console
$ uv pip sync requirements.txt
```
To sync an environment with a `pyproject.toml` file:
```bash
uv pip sync pyproject.toml
```console
$ uv pip sync pyproject.toml
```
## Adding constraints
@ -119,8 +119,8 @@ pydantic<2.0
To use a constraints file:
```bash
uv pip compile requirements.in --constraint constraints.txt
```console
$ uv pip compile requirements.in --constraint constraints.txt
```
Note that multiple constraints can be defined in each file and multiple files can be used.
@ -147,8 +147,8 @@ c>=2.0
To use an overrides file:
```bash
uv pip compile requirements.in --override overrides.txt
```console
$ uv pip compile requirements.in --override overrides.txt
```
Now, resolution can succeed. However, note that if `a` is _correct_ that it does not support

35
docs/pip/environments.md
View file

@ -9,25 +9,22 @@ installation's environment. Unlike `pip`, uv requires using a virtual environmen
## Creating a virtual environment
uv supports creating virtual environments:
uv supports creating virtual environments, e.g., to create a virtual environment at `.venv`:
```bash
# Create a virtual environment at `.venv`
uv venv
```console]
$ uv venv
```
A specific name or path can be specified:
A specific name or path can be specified, e.g., to create a virtual environment at `my-name`:
```bash
# Create a virtual environment at `my-name`
uv venv my-name
```console
$ uv venv my-name
```
A Python version can be requested:
A Python version can be requested, e.g., to create a virtual environment with Python 3.11:
```bash
# Create a virtual environment with Python 3.11
uv venv --python 3.11
```console
$ uv venv --python 3.11
```
Note this requires the requested Python version to be available on the system. However, if
@ -39,8 +36,8 @@ documentation for more details.
When using the default virtual environment name, uv will automatically find and use the virtual
environment during subsequent invocations.
```bash
uv venv
```console
$ uv venv
# Install a package in the new virtual environment
uv pip install ruff
@ -48,12 +45,12 @@ uv pip install ruff
The virtual environment can be "activated" to make its packages available:
```bash
# On macOS and Linux.
source .venv/bin/activate
```console title="macOS and Linux"
$ source .venv/bin/activate
```
# On Windows.
.venv\Scripts\activate
```console title="Windows"
$ .venv\Scripts\activate
```
## Using arbitrary Python environments

20
docs/pip/inspection.md
View file

@ -4,28 +4,28 @@
To list all of the packages in the environment:
```bash
uv pip list
```console
$ uv pip list
```
To list the packages in a JSON format:
```bash
uv pip list --format json
```console
$ uv pip list --format json
```
To list all of the packages in the environment in a `requirements.txt` format:
```bash
uv pip freeze
```console
$ uv pip freeze
```
## Inspecting a package
To show information about an installed package, e.g., `numpy`:
```bash
uv pip show numpy
```console
$ uv pip show numpy
```
Multiple packages can be inspected at once.
@ -37,6 +37,6 @@ multiple steps.
To check for conflicts or missing dependencies in the environment:
```bash
uv pip check
```console
$ uv pip check
```

74
docs/pip/packages.md
View file

@ -4,57 +4,57 @@
To install a package into the virtual environment, e.g., Flask:
```bash
uv pip install flask
```console
$ uv pip install flask
```
To install a package with optional dependencies enabled, e.g., Flask with the "dotenv" extra:
```bash
uv pip install "flask[dotenv]"
```console
$ uv pip install "flask[dotenv]"
```
To install multiple packages, e.g., Flask and Ruff:
```bash
uv pip install flask ruff
```console
$ uv pip install flask ruff
```
To install a package with a constraint, e.g., Ruff v0.2.0 or newer:
```bash
uv pip install 'ruff>=0.2.0'
```console
$ uv pip install 'ruff>=0.2.0'
```
To install a package at a specific version, e.g., Ruff v0.3.0:
```bash
uv pip install 'ruff==0.3.0'
```console
$ uv pip install 'ruff==0.3.0'
```
To install a package from the disk:
```bash
uv pip install "ruff @ ./projects/ruff"
```console
$ uv pip install "ruff @ ./projects/ruff"
```
To install a package from GitHub:
```bash
uv pip install "git+https://github.com/astral-sh/ruff"
```console
$ uv pip install "git+https://github.com/astral-sh/ruff"
```
To install a package from GitHub at a specific reference:
```bash
# Install a tag
uv pip install "git+https://github.com/astral-sh/ruff@v0.2.0"
```console
$ # Install a tag
$ uv pip install "git+https://github.com/astral-sh/ruff@v0.2.0"
# Install a commit
uv pip install "git+https://github.com/astral-sh/ruff@1fadefa67b26508cc59cf38e6130bde2243c929d"
$ # Install a commit
$ uv pip install "git+https://github.com/astral-sh/ruff@1fadefa67b26508cc59cf38e6130bde2243c929d"
# Install a branch
uv pip install "git+https://github.com/astral-sh/ruff@main"
$ # Install a branch
$ uv pip install "git+https://github.com/astral-sh/ruff@main"
```
See the [Git authentication](../configuration/authentication.md#git-authentication) documentation
@ -66,14 +66,14 @@ Editable packages do not need to be reinstalled for change to their source code
To install the current project as an editable package
```bash
uv pip install -e .
```console
$ uv pip install -e .
```
To install a project in another directory as an editable package:
```bash
uv pip install -e ruff @ ./project/ruff
```console
$ uv pip install -e ruff @ ./project/ruff
```
## Installing packages from files
@ -82,8 +82,8 @@ Multiple packages can be installed at once from standard file formats.
Install from a `requirements.txt` file:
```bash
uv pip install -r requirements.txt
```console
$ uv pip install -r requirements.txt
```
See the [`uv pip compile`](./compile.md) documentation for more information on `requirements.txt`
@ -91,32 +91,32 @@ files.
Install from a `pyproject.toml` file:
```bash
uv pip install -r pyproject.toml
```console
$ uv pip install -r pyproject.toml
```
Install from a `pyproject.toml` file with optional dependencies enabled, e.g., the "foo" extra:
```bash
uv pip install -r pyproject.toml --extra foo
```console
$ uv pip install -r pyproject.toml --extra foo
```
Install from a `pyproject.toml` file with all optional dependencies enabled:
```bash
uv pip install -r pyproject.toml --all-extras
```console
$ uv pip install -r pyproject.toml --all-extras
```
## Uninstalling a package
To uninstall a package, e.g., Flask:
```bash
uv pip uninstall flask
```console
$ uv pip uninstall flask
```
To uninstall multiple packages, e.g., Flask and Ruff:
```bash
uv pip uninstall flask ruff
```console
$ uv pip uninstall flask ruff
```

2
mkdocs.template.yml
View file

@ -89,8 +89,8 @@ nav:
- guides/index.md
- Installing Python: guides/install-python.md
- Running scripts: guides/scripts.md
- Using tools: guides/tools.md
- Working on projects: guides/projects.md
- Using tools: guides/tools.md
- Concepts:
- concepts/index.md
- Projects: concepts/projects.md