uv: руководство для начинающих -- инструмент управления пакетами и окружением Python
В разработке на Python управление пакетами и изоляция окружений — это проблемы, с которыми сталкивается каждый разработчик. Будь то медлительность pip, громоздкость virtualenv или раздутость conda,uvвсё это заставляет разработчиков с нетерпением ждать более эффективного решения.
Что такое uv?
uv — это менеджер пакетов Python и менеджер окружений, разработанный Astral на Rust. Его основная цель — обеспечить производительность в 10-100 раз выше, чем у существующих инструментов, при сохранении простого и интуитивно понятного пользовательского опыта.
uv может заменить такие инструменты, как pip, virtualenv, pip-tools и pyenv, предоставляя универсальные решения для управления зависимостями, создания виртуальных окружений и управления версиями Python.
Преимущества uv
- Чрезвычайно быстрый: Поскольку он написан на Rust, производительность uv намного превосходит производительность pip и других инструментов управления пакетами, а скорость установки зависимостей можно увеличить в 10-100 раз.
- Интегрированная функциональность: Он объединяет разрешение зависимостей, установку пакетов, управление окружением и управление версиями Python в одном инструменте, избавляя от необходимости устанавливать и изучать несколько инструментов.
- Детерминированные сборки: uv генерирует
uv.lockфайл, гарантируя, что точно такие же версии зависимостей можно установить в любом окружении, избегая проблемы «работает на моей машине». - Совместимость с существующими инструментами: uv может обрабатывать
requirements.txtиpyproject.toml, и может бесшовно заменить pip в существующих рабочих процессах.
Установка uv
Установка в macOS
Рекомендуется устанавливать через Homebrew:
brew install uv
Или используйте официальный скрипт установки:
curl -LsSf https://astral.sh/uv/install.sh | sh
Установка в Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
Установка в Windows
Использование Winget:
winget install uv
Или используйте официальный установочный скрипт (PowerShell):
irm https://astral.sh/uv/install.ps1 | iex
После установки проверьте, прошла ли она успешно:
uv --version
Вывод похож на следующий, что свидетельствует об успешной установке:
uv 0.8.14 (Homebrew 2025-08-28)
1. Управление версиями Python
uv имеет встроенную функцию управления версиями Python, поэтому нет необходимости устанавливать дополнительные инструменты, такие как pyenv.
Просмотр доступных версий Python:
uv python list
Результат вывода аналогичен следующему:
cpython-3.14.0rc2-macos-aarch64-none <download available> cpython-3.13.7-macos-aarch64-none <download available> cpython-3.12.11-macos-aarch64-none <download available> cpython-3.11.13-macos-aarch64-none <download available> cpython-3.10.18-macos-aarch64-none <download available> cpython-3.9.6-macos-aarch64-none /usr/bin/python3 pypy-3.11.13-macos-aarch64-none <download available>
Установка конкретной версии Python:
# 安装最新的 Python 3.12 uv python install 3.12 # 安装特定版本 uv python install 3.11.6 # 安装 PyPy 版本 uv python install pypy3.10
Установка глобальной версии Python по умолчанию:
uv python default 3.12
Зафиксируйте версию Python для текущего проекта (будет создан.python-versionфайл):
uv python pin 3.12
После выполнения этой команды в текущем каталоге проекта будет создан файл .python-version. При открытии он отображает содержимое с номером версии:
3.12
2. Управление виртуальными средами
Создание виртуального окружения:
# 在当前目录创建名为 .venv 的虚拟环境（使用系统默认 Python） uv venv # 使用指定 Python 版本创建虚拟环境 uv venv --python 3.12
Активируйте виртуальную среду:
# macOS / Linux source .venv/bin/activate # Windows（PowerShell） .venv\Scripts\activate
Выйдите из виртуальной среды:
deactivate
В повседневной разработке вы можете использовать
uv runчтобы напрямую запускать скрипты без ручной активации виртуальной среды.
3. Управление пакетами (режим совместимости с pip)
uv предоставляет интерфейс командной строки, полностью совместимый с pip, который может напрямую заменять команды pip в существующих рабочих процессах:
Установка пакетов:
# 安装最新版本 uv pip install requests # 安装特定版本 uv pip install requests==2.31.0 # 从 requirements.txt 批量安装 uv pip install -r requirements.txt
Обновление пакетов:
uv pip install --upgrade requests
Удаление пакетов:
uv pip uninstall requests
Просмотр установленных пакетов:
uv pip list
Экспорт зависимостей текущей среды в requirements.txt:
uv pip freeze > requirements.txt
4. Управление проектом (рекомендуемый подход)
uv поддерживаетpyproject.toml-ориентированный современный подход к управлению проектами, который рекомендуется больше, чем режим pip, особенно подходит для командной работы и развертывания в нескольких средах.
Инициализация проекта
uv init my_project cd my_project
Это создаст следующую базовую структуру проекта:
my_project/ ├── pyproject.toml # 项目配置和依赖声明 ├── .python-version # 固定 Python 版本 ├── README.md └── main.py
Добавление и удаление зависимостей
В режиме проекта рекомендуется использоватьuv addиuv removeдля управления зависимостями; они будут автоматически обновлятьсяpyproject.tomlиuv.lock：
# 添加生产依赖 uv add requests # 添加指定版本的依赖 uv add "requests>=2.31.0" # 添加开发依赖（只在开发环境使用，如测试框架） uv add --dev pytest ruff # 移除依赖 uv remove requests
Установка всех зависимостей проекта (uv sync)
После клонирования проекта или обновленияpyproject.toml, выполните следующую команду, чтобы установить все зависимости одним кликом:
uv sync
Пояснение uv sync:Аналогично
pip install -r requirements.txt, он, основываясь наpyproject.tomlиuv.lockустановит все зависимости, гарантируя, что окружение точно такое же, как у других разработчиков. Если установка медленная, вы можете, вpyproject.tomlнастройте внутренний зеркальный источник:[tool.uv] index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
Генерация/обновление файлов блокировки
uv lock
Эта команда проанализируетpyproject.tomlзависимости и сгенерирует (или обновит) файлuv.lockфайл.uv.lockЕго следует закоммитить в репозиторий системы контроля версий, чтобы все участники команды использовали в точности одинаковые версии зависимостей.
5. Запуск скриптов (uv run)
uv run— очень практичная команда в uv, позволяющая вам, без ручной активации виртуального окружения,напрямую запускать скрипты или команды. uv автоматически найдёт и использует нужное окружение:
# 直接运行 Python 脚本 uv run main.py # 运行项目中的测试 uv run pytest # 运行任意命令（在虚拟环境的上下文中执行） uv run python -c "import requests; print(requests.__version__)"
Использованиеuv runпо сравнению с ручной активацией окружения имеет следующие преимущества: вы не будете случайно использовать неправильную версию Python и не забудете активировать окружение, из-за чего пакеты могут не найтись. Особенно подходит для использования в CI/CD и автоматизации скриптов.
Переход на uv
Если вы используете другие инструменты, вы можете перейти на uv следующими способами:
Переход с pip + virtualenv:
# 创建并激活虚拟环境 uv venv source .venv/bin/activate # 安装原有依赖 uv pip install -r requirements.txt
Переход с pip-tools:
# 编译依赖（替代 pip-compile） uv pip compile requirements.in -o requirements.txt # 同步环境（替代 pip-sync） uv pip sync requirements.txt
Миграция с poetry или pdm:
# 直接使用现有的 pyproject.toml uv syncДругие расширения