# UV — Ultra-Fast Python Package Manager
> Rust-powered Python package and project manager. 10-100x faster than pip. Drop-in replacement with lockfiles, virtual environments, and Python version management.
## Install
Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:
# uv Companion Guide: Install, Projects, pin and FAQ
Bilingual companion guide for the uv skill asset: install paths, project and script workflows, pinned Python, permissions, limits and FAQ.
## Quick Use
This companion documentation is written for the existing `uv` skill asset. Its UUID, owner, entrypoint (`UV — Ultra-Fast Python Package Manager`) and installation contract stay unchanged; the asset's original files were not edited, and no installer was run.
The original asset ships no install files, so treat uv as a tool you install yourself from the upstream project before using anything in this guide.
Documented install options (run them yourself; source reviewed; runtime not tested):
```bash
# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```
```bash
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
```bash
# Or from PyPI
pip install uv
```
Verify the tool is on your PATH with `uv --version`, then check that the pip-compatible path works: `uv pip install requests`.
## Introduction
uv is an extremely fast Python package and project manager written in Rust, backed by [Astral](https://astral.sh), the creators of [Ruff](https://github.com/astral-sh/ruff) and [ty](https://github.com/astral-sh/ty). The upstream README describes it as a single tool replacing `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `twine` and `virtualenv`, with a universal lockfile and self-managed Python versions. This guide restates the documented workflows in a shorter, bilingual form so you can decide whether the asset fits your project before reading the full README, which the publisher appends unchanged.
## Prerequisites
- A shell on macOS, Linux or Windows; no Rust or Python is required for the standalone installers.
- Network access to download the installer or PyPI package.
- An existing project you are comfortable changing, or a scratch directory for the examples.
## Permissions and limitations
- The original asset records `executes_code=false`, `modifies_global_config=false`, no required secrets and no absolute paths, with network access enabled. It contains no files and no verification commands, so nothing about it was executed while preparing this text.
- Installing uv is your decision and your action; the upstream installer places binaries on your machine, so review the script before running it if your policy requires that.
- `uv python install` and `uv tool install` change state on your system, and lockfile synchronisation can replace packages in a virtual environment. Test on a copy first.
- This guide makes no claim about runtime behaviour, performance numbers or production suitability beyond what the upstream README states. Source reviewed; runtime not tested.
- The asset is Apache-2.0 / MIT dual licensed upstream; this companion adds no licensing terms.
## Working with projects
The documented project flow is init, add, run, lock, sync:
```console
$ uv init example
$ cd example
$ uv add ruff
$ uv run ruff check
$ uv lock
$ uv sync
```
## Managing Python versions
```console
$ uv python install 3.12 3.13 3.14
$ uv python pin 3.11
```
`uv python pin` writes a `.python-version` file in the current directory, which is the part people usually forget when a teammate's interpreter differs from theirs.
## Running tools and scripts
`uvx` is an alias for `uv tool run`, so a published tool can run in an ephemeral environment without being installed permanently:
```console
$ uvx pycowsay 'hello world!'
```
Single-file scripts can declare dependencies inline and then run in an isolated environment:
```console
$ uv add --script example.py requests
$ uv run example.py
```
## FAQ
**Q: I only want a faster pip. Do I have to adopt the project workflow?**
A: No. The `uv pip` interface is documented as a drop-in replacement for common pip, pip-tools and virtualenv commands, for example `uv pip install requests`, `uv venv` and `uv pip sync requirements.txt`. The project commands (`uv init`, `uv add`, `uv run`) are a separate layer.
**Q: uv self update failed or the command is not found — why?**
A: `uv self update` is documented as available only for installs done with the standalone installer; a PyPI install is updated through pip or pipx instead. A missing command usually means the install directory is not on your PATH. Both points follow the upstream README; this was not tested here.
## Source and thanks
- Source: [astral-sh/uv](https://github.com/astral-sh/uv), README at commit `46b84fd0bfec23b72f29e8e2185ba68a65052f48`.
- Created by Astral; Apache-2.0 / MIT dual licensed upstream.
- This companion guide was not run against a live installation. Source reviewed; runtime not tested.
## Complete upstream material
# uv
An extremely fast Python package and project manager, written in Rust.
## Highlights
- 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`.
- Provides [comprehensive project management](#projects), with a
[universal lockfile](https://docs.astral.sh/uv/concepts/projects/layout#the-lockfile).
- [Runs scripts](#scripts), with support for
[inline dependency metadata](https://docs.astral.sh/uv/guides/scripts#declaring-script-dependencies).
- [Installs and manages](#python-versions) Python versions.
- [Runs and installs](#tools) 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) for
scalable projects.
- Disk-space efficient, with a [global cache](https://docs.astral.sh/uv/concepts/cache) for
dependency deduplication.
- 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) and [ty](https://github.com/astral-sh/ty).
## Installation
Install uv with our standalone installers:
```bash
# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh
```
```bash
# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
Or, from [PyPI](https://pypi.org/project/uv/):
```bash
# With pip.
pip install uv
```
```bash
# Or pipx.
pipx install uv
```
If installed via the standalone installer, uv can update itself to the latest version:
```bash
uv self update
```
See the [installation documentation](https://docs.astral.sh/uv/getting-started/installation/) for
details and alternative installation methods.
## Documentation
uv's documentation is available at [docs.astral.sh/uv](https://docs.astral.sh/uv).
Additionally, the command line reference documentation can be viewed with `uv help`.
## Features
### Projects
uv manages project dependencies and environments, with support for lockfiles, workspaces, and more,
similar to `rye` or `poetry`:
```console
$ uv init example
Initialized project `example` at `/home/user/example`
$ cd example
$ uv add ruff
Creating virtual environment at: .venv
Resolved 2 packages in 170ms
Built example @ file:///home/user/example
Prepared 2 packages in 627ms
Installed 2 packages in 1ms
+ example==0.1.0 (from file:///home/user/example)
+ ruff==0.5.0
$ uv run ruff check
All checks passed!
$ uv lock
Resolved 2 packages in 0.33ms
$ uv sync
Resolved 2 packages in 0.70ms
Checked 1 package in 0.02ms
```
See the [project documentation](https://docs.astral.sh/uv/guides/projects/) to get started.
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.
### 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`.
Run a tool in an ephemeral environment using `uvx` (an alias for `uv tool run`):
```console
$ uvx pycowsay 'hello world!'
Resolved 1 package in 167ms
Installed 1 package in 9ms
+ pycowsay==0.0.0.2
"""
------------
< hello world! >
------------
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
```
Install a tool with `uv tool install`:
```console
$ uv tool install ruff
Resolved 1 package in 6ms
Installed 1 package in 2ms
+ ruff==0.5.0
Installed 1 executable: ruff
$ ruff --version
ruff 0.5.0
```
See the [tools documentation](https://docs.astral.sh/uv/guides/tools/) to get started.
### Python versions
uv installs Python and allows quickly switching between versions.
Install multiple Python versions:
```console
$ uv python install 3.12 3.13 3.14
Installed 3 versions in 972ms
+ cpython-3.12.12-macos-aarch64-none (python3.12)
+ cpython-3.13.9-macos-aarch64-none (python3.13)
+ cpython-3.14.0-macos-aarch64-none (python3.14)
```
Download Python versions as needed:
```console
$ uv venv --python 3.12.0
Using Python 3.12.0
Creating virtual environment 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:
```console
$ uv python pin 3.11
Pinned `.python-version` to `3.11`
```
See the [Python installation documentation](https://docs.astral.sh/uv/guides/install-python/) to get
started.
### The pip interface
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,
platform-independent resolutions, reproducible resolutions, alternative resolution strategies, and
more.
Migrate to uv without changing your existing workflows — and experience a 10-100x speedup — with the
`uv pip` interface.
Compile requirements into a platform-independent requirements file:
```console
$ uv pip compile requirements.in \
--universal \
--output-file requirements.txt
Resolved 43 packages in 12ms
```
Create a virtual environment:
```console
$ uv venv
Using Python 3.12.3
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate
```
Install the locked requirements:
```console
$ uv pip sync requirements.txt
Resolved 43 packages in 11ms
Installed 43 packages in 208ms
+ babel==2.15.0
+ black==24.4.2
+ certifi==2024.7.4
...
```
See the [pip interface documentation](https://docs.astral.sh/uv/pip/index/) to get started.
## Contributing
We are passionate about supporting contributors of all levels of experience and would love to see
you get involved in the project. See the
[contributing guide](https://github.com/astral-sh/uv?tab=contributing-ov-file#contributing) to get
started.
## FAQ
#### How do you pronounce uv?
It's pronounced as "you - vee" ([`/juː viː/`](https://en.wikipedia.org/wiki/Help:IPA/English#Key))
#### How should I stylize uv?
Just "uv", please. See the [style guide](https://github.com/astral-sh/uv/blob/46b84fd0bfec23b72f29e8e2185ba68a65052f48/STYLE.md#styling-uv) for details.
#### What platforms does uv support?
See uv's [platform support](https://docs.astral.sh/uv/reference/platforms/) document.
#### Is uv ready for production?
Yes, uv is stable and widely used in production. See uv's
[versioning policy](https://docs.astral.sh/uv/reference/versioning/) document for details.
## Acknowledgements
uv's dependency resolver uses [PubGrub](https://github.com/pubgrub-rs/pubgrub) under the hood. We're
grateful to the PubGrub maintainers, especially [Jacob Finkelman](https://github.com/Eh2406), for
their support.
uv's Git implementation is based on [Cargo](https://github.com/rust-lang/cargo).
Some of uv's optimizations are inspired by the great work we've seen in [pnpm](https://pnpm.io/),
[Orogene](https://github.com/orogene/orogene), and [Bun](https://github.com/oven-sh/bun). We've also
learned a lot from Nathaniel J. Smith's [Posy](https://github.com/njsmith/posy) and adapted its
[trampoline](https://github.com/njsmith/posy/tree/main/src/trampolines/windows-trampolines/posy-trampoline)
for Windows support.
## License
uv is licensed under either of
- Apache License, Version 2.0, ([LICENSE-APACHE](https://github.com/astral-sh/uv/blob/46b84fd0bfec23b72f29e8e2185ba68a65052f48/LICENSE-APACHE) or
)
- MIT license ([LICENSE-MIT](https://github.com/astral-sh/uv/blob/46b84fd0bfec23b72f29e8e2185ba68a65052f48/LICENSE-MIT) or )
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in uv
by you, as defined in the Apache-2.0 license, shall be dually licensed as above, without any
additional terms or conditions.
## Source and license
[Source](https://github.com/astral-sh/uv/blob/46b84fd0bfec23b72f29e8e2185ba68a65052f48/README.md) · [License](https://github.com/astral-sh/uv/blob/46b84fd0bfec23b72f29e8e2185ba68a65052f48/LICENSE-MIT) · `46b84fd0bfec23b72f29e8e2185ba68a65052f48`
MIT License
Copyright (c) 2025 Astral Software Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
---
# uv 双语使用指南：安装、项目管理与常见问题
uv 技能资产的双语配套指南：安装方式、项目与脚本工作流、Python 版本固定、权限限制与常见问题。
## 快速使用
本文是已有 `uv` 技能资产的中文配套说明。该资产的 UUID、归属、入口（`UV — Ultra-Fast Python Package Manager`）与安装约定保持不变；原有文件没有被修改，也没有运行任何安装程序。
原资产不包含任何安装文件，因此请先自行从上游项目安装 uv，再使用本文中的内容。
上游文档给出的安装方式（请自行执行；已审阅来源，未进行运行时测试）：
```bash
# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```
```bash
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
```bash
# Or from PyPI
pip install uv
```
安装后用 `uv --version` 确认命令已进入 PATH，再用 `uv pip install requests` 检查兼容 pip 的用法是否可用。
## 简介
uv 是用 Rust 编写的极快的 Python 包与项目管理器，由 [Ruff](https://github.com/astral-sh/ruff) 和 [ty](https://github.com/astral-sh/ty) 的作者 [Astral](https://astral.sh) 维护。上游 README 称它可以用一个工具替代 `pip`、`pip-tools`、`pipx`、`poetry`、`pyenv`、`twine` 和 `virtualenv`，并提供统一锁文件与 Python 版本管理。本文把文档化的流程压缩成中英双语要点，方便你先判断是否适合，再阅读由发布方可完整附加的原始 README。
## 前置条件
- macOS、Linux 或 Windows 上可用的命令行；独立安装脚本不要求本机已装 Rust 或 Python。
- 可访问网络以下载安装脚本或 PyPI 包。
- 一个你愿意改动的项目，或用于示例的临时目录。
## 权限与限制
- 原资产记录为 `executes_code=false`、`modifies_global_config=false`，无必需密钥、无绝对路径，允许网络访问。它不含任何文件与校验命令，因此撰写本文时没有执行其中任何内容。
- 安装 uv 是你自己的决定和操作；上游脚本会向本机写入可执行文件，如你的规范要求，请先审阅脚本内容。
- `uv python install` 与 `uv tool install` 会改变系统状态，锁文件同步也可能替换虚拟环境中的包，建议先在副本上试。
- 除上游 README 已写明的内容外，本文不对运行时行为、性能数字或生产可用性作任何断言。已审阅来源，未进行运行时测试。
- 该资产在上游采用 Apache-2.0 / MIT 双许可；本配套说明不新增任何许可条款。
## 项目工作流
文档化的项目流程是 init、add、run、lock、sync：
```console
$ uv init example
$ cd example
$ uv add ruff
$ uv run ruff check
$ uv lock
$ uv sync
```
## 管理 Python 版本
```console
$ uv python install 3.12 3.13 3.14
$ uv python pin 3.11
```
`uv python pin` 会在当前目录写入 `.python-version` 文件；当同事的解释器版本与你不同时，通常就是漏掉了这一步。
## 运行工具与脚本
`uvx` 是 `uv tool run` 的别名，可以在临时环境中运行已发布的工具，而不必长期安装：
```console
$ uvx pycowsay 'hello world!'
```
单文件脚本可以把依赖写在脚本内联元数据里，然后在隔离环境中运行：
```console
$ uv add --script example.py requests
$ uv run example.py
```
## 常见问题
**问：我只想要更快的 pip，必须改用项目工作流吗？**
答：不必。`uv pip` 接口文档中说明它是 pip、pip-tools 与 virtualenv 常用命令的替代，例如 `uv pip install requests`、`uv venv`、`uv pip sync requirements.txt`；项目命令（`uv init`、`uv add`、`uv run`）是另一层能力。
**问：`uv self update` 失败或提示找不到命令，是什么原因？**
答：上游 README 说明 `uv self update` 只对使用独立安装脚本安装的版本可用，通过 PyPI 安装的应改用 pip 或 pipx 更新；而命令找不到通常意味着安装目录不在 PATH 中。这两点均来自上游文档，本文未做验证。
## 来源与致谢
- 来源：[astral-sh/uv](https://github.com/astral-sh/uv)，对应提交 `46b84fd0bfec23b72f29e8e2185ba68a65052f48` 的 README。
- 由 Astral 创建；上游采用 Apache-2.0 / MIT 双许可。
- 本配套说明未在真实安装环境中运行。已审阅来源，未进行运行时测试。
## 完整上游材料译文
# uv
一个用 Rust 编写的、速度极快的 Python 包和项目管理器。
## 来源与许可证
[Source](https://github.com/astral-sh/uv/blob/46b84fd0bfec23b72f29e8e2185ba68a65052f48/README.md) · [License](https://github.com/astral-sh/uv/blob/46b84fd0bfec23b72f29e8e2185ba68a65052f48/LICENSE-MIT) · `46b84fd0bfec23b72f29e8e2185ba68a65052f48`
MIT License
Copyright (c) 2025 Astral Software Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
---
Source: https://tokrepo.com/en/workflows/uv-ultra-fast-python-package-manager-0a5dd5b3
Author: Script Depot
An extremely fast Python package and project manager, written in Rust.
