鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

uv-package-manager

提供超高速 Python依赖管理与项目环境构建能力,支持新建项目初始化、虚拟环境创建与管理、多版本 Python 安装、依赖增删改查、锁文件生成与同步、离线安装及 CI/CD 流水线加速,适用于现代 Python 开发全流程优化。

软件开发
访问 GitHub
文档Skills.MD
name
uv-package-manager
description
Master the uv package manager for fast Python dependency management, virtual environments, and modern Python project workflows. Use when setting up Python projects, managing dependencies, or optimizing Python development workflows with uv.

UV Package Manager

Comprehensive guide to using uv, an extremely fast Python package installer and resolver written in Rust, for modern Python project management and dependency workflows.

When to Use This Skill

  • Setting up new Python projects quickly
  • Managing Python dependencies faster than pip
  • Creating and managing virtual environments
  • Installing Python interpreters
  • Resolving dependency conflicts efficiently
  • Migrating from pip/pip-tools/poetry
  • Speeding up CI/CD pipelines
  • Managing monorepo Python projects
  • Working with lockfiles for reproducible builds
  • Optimizing Docker builds with Python dependencies

Core Concepts

1. What is uv?

  • Ultra-fast package installer: 10-100x faster than pip
  • Written in Rust: Leverages Rust's performance
  • Drop-in pip replacement: Compatible with pip workflows
  • Virtual environment manager: Create and manage venvs
  • Python installer: Download and manage Python versions
  • Resolver: Advanced dependency resolution
  • Lockfile support: Reproducible installations

2. Key Features

  • Blazing fast installation speeds
  • Disk space efficient with global cache
  • Compatible with pip, pip-tools, poetry
  • Comprehensive dependency resolution
  • Cross-platform support (Linux, macOS, Windows)
  • No Python required for installation
  • Built-in virtual environment support

3. UV vs Traditional Tools

  • vs pip: 10-100x faster, better resolver
  • vs pip-tools: Faster, simpler, better UX
  • vs poetry: Faster, less opinionated, lighter
  • vs conda: Faster, Python-focused

Installation

Quick Install

▼
bash
复制代码
# macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows (PowerShell) powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Using pip (if you already have Python) pip install uv # Using Homebrew (macOS) brew install uv # Using cargo (if you have Rust) cargo install --git https://github.com/astral-sh/uv uv

Verify Installation

▼
bash
复制代码
uv --version # uv 0.x.x

Quick Start

Create a New Project

▼
bash
复制代码
# Create new project with virtual environment uv init my-project cd my-project # Or create in current directory uv init . # Initialize creates: # - .python-version (Python version) # - pyproject.toml (project config) # - README.md # - .gitignore

Install Dependencies

▼
bash
复制代码
# Install packages (creates venv if needed) uv add requests pandas # Install dev dependencies uv add --dev pytest black ruff # Install from requirements.txt uv pip install -r requirements.txt # Install from pyproject.toml uv sync

Virtual Environment Management

Pattern 1: Creating Virtual Environments

▼
bash
复制代码
# Create virtual environment with uv uv venv # Create with specific Python version uv venv --python 3.12 # Create with custom name uv venv my-env # Create with system site packages uv venv --system-site-packages # Specify location uv venv /path/to/venv

Pattern 2: Activating Virtual Environments

▼
bash
复制代码
# Linux/macOS source .venv/bin/activate # Windows (Command Prompt) .venv\Scripts\activate.bat # Windows (PowerShell) .venv\Scripts\Activate.ps1 # Or use uv run (no activation needed) uv run python script.py uv run pytest

Pattern 3: Using uv run

▼
bash
复制代码
# Run Python script (auto-activates venv) uv run python app.py # Run installed CLI tool uv run black . uv run pytest # Run with specific Python version uv run --python 3.11 python script.py # Pass arguments uv run python script.py --arg value

Package Management

Pattern 4: Adding Dependencies

▼
bash
复制代码
# Add package (adds to pyproject.toml) uv add requests # Add with version constraint uv add "django>=4.0,<5.0" # Add multiple packages uv add numpy pandas matplotlib # Add dev dependency uv add --dev pytest pytest-cov # Add optional dependency group uv add --optional docs sphinx # Add from git uv add git+https://github.com/user/repo.git # Add from git with specific ref uv add git+https://github.com/user/repo.git@v1.0.0 # Add from local path uv add ./local-package # Add editable local package uv add -e ./local-package

Pattern 5: Removing Dependencies

▼
bash
复制代码
# Remove package uv remove requests # Remove dev dependency uv remove --dev pytest # Remove multiple packages uv remove numpy pandas matplotlib

Pattern 6: Upgrading Dependencies

▼
bash
复制代码
# Upgrade specific package uv add --upgrade requests # Upgrade all packages uv sync --upgrade # Upgrade package to latest uv add --upgrade requests # Show what would be upgraded uv tree --outdated

Pattern 7: Locking Dependencies

▼
bash
复制代码
# Generate uv.lock file uv lock # Update lock file uv lock --upgrade # Lock without installing uv lock --no-install # Lock specific package uv lock --upgrade-package requests

Python Version Management

Pattern 8: Installing Python Versions

▼
bash
复制代码
# Install Python version uv python install 3.12 # Install multiple versions uv python install 3.11 3.12 3.13 # Install latest version uv python install # List installed versions uv python list # Find available versions uv python list --all-versions

Pattern 9: Setting Python Version

▼
bash
复制代码
# Set Python version for project uv python pin 3.12 # This creates/updates .python-version file # Use specific Python version for command uv --python 3.11 run python script.py # Create venv with specific version uv venv --python 3.12

Project Configuration

Pattern 10: pyproject.toml with uv

▼
toml
复制代码
[project] name = "my-project" version = "0.1.0" description = "My awesome project" readme = "README.md" requires-python = ">=3.8" dependencies = [ "requests>=2.31.0", "pydantic>=2.0.0", "click>=8.1.0", ] [project.optional-dependencies] dev = [ "pytest>=7.4.0", "pytest-cov>=4.1.0", "black>=23.0.0", "ruff>=0.1.0", "mypy>=1.5.0", ] docs = [ "sphinx>=7.0.0", "sphinx-rtd-theme>=1.3.0", ] [build-system] requires = ["hatchling"] build-backend = "hatchling.build" [tool.uv] dev-dependencies = [ # Additional dev dependencies managed by uv ] [tool.uv.sources] # Custom package sources my-package = { git = "https://github.com/user/repo.git" }

Pattern 11: Using uv with Existing Projects

▼
bash
复制代码
# Migrate from requirements.txt uv add -r requirements.txt # Migrate from poetry # Already have pyproject.toml, just use: uv sync # Export to requirements.txt uv pip freeze > requirements.txt # Export with hashes uv pip freeze --require-hashes > requirements.txt

Advanced Workflows

Pattern 12: Monorepo Support

▼
bash
复制代码
# Project structure # monorepo/ # packages/ # package-a/ # pyproject.toml # package-b/ # pyproject.toml # pyproject.toml (root) # Root pyproject.toml [tool.uv.workspace] members = ["packages/*"] # Install all workspace packages uv sync # Add workspace dependency uv add --path ./packages/package-a

Pattern 13: CI/CD Integration

▼
yaml
复制代码
# .github/workflows/test.yml name: Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install uv uses: astral-sh/setup-uv@v2 with: enable-cache: true - name: Set up Python run: uv python install 3.12 - name: Install dependencies run: uv sync --all-extras --dev - name: Run tests run: uv run pytest - name: Run linting run: | uv run ruff check . uv run black --check .

Pattern 14: Docker Integration

▼
dockerfile
复制代码
# Dockerfile FROM python:3.12-slim # Install uv COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv # Set working directory WORKDIR /app # Copy dependency files COPY pyproject.toml uv.lock ./ # Install dependencies RUN uv sync --frozen --no-dev # Copy application code COPY . . # Run application CMD ["uv", "run", "python", "app.py"]

Optimized multi-stage build:

▼
dockerfile
复制代码
# Multi-stage Dockerfile FROM python:3.12-slim AS builder # Install uv COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv WORKDIR /app # Install dependencies to venv COPY pyproject.toml uv.lock ./ RUN uv sync --frozen --no-dev --no-editable # Runtime stage FROM python:3.12-slim WORKDIR /app # Copy venv from builder COPY --from=builder /app/.venv .venv COPY . . # Use venv ENV PATH="/app/.venv/bin:$PATH" CMD ["python", "app.py"]

Pattern 15: Lockfile Workflows

▼
bash
复制代码
# Create lockfile (uv.lock) uv lock # Install from lockfile (exact versions) uv sync --frozen # Update lockfile without installing uv lock --no-install # Upgrade specific package in lock uv lock --upgrade-package requests # Check if lockfile is up to date uv lock --check # Export lockfile to requirements.txt uv export --format requirements-txt > requirements.txt # Export with hashes for security uv export --format requirements-txt --hash > requirements.txt

Performance Optimization

Pattern 16: Using Global Cache

▼
bash
复制代码
# UV automatically uses global cache at: # Linux: ~/.cache/uv # macOS: ~/Library/Caches/uv # Windows: %LOCALAPPDATA%\uv\cache # Clear cache uv cache clean # Check cache size uv cache dir

Pattern 17: Parallel Installation

▼
bash
复制代码
# UV installs packages in parallel by default # Control parallelism uv pip install --jobs 4 package1 package2 # No parallel (sequential) uv pip install --jobs 1 package

Pattern 18: Offline Mode

▼
bash
复制代码
# Install from cache only (no network) uv pip install --offline package # Sync from lockfile offline uv sync --frozen --offline

Comparison with Other Tools

uv vs pip

▼
bash
复制代码
# pip python -m venv .venv source .venv/bin/activate pip install requests pandas numpy # ~30 seconds # uv uv venv uv add requests pandas numpy # ~2 seconds (10-15x faster)

uv vs poetry

▼
bash
复制代码
# poetry poetry init poetry add requests pandas poetry install # ~20 seconds # uv uv init uv add requests pandas uv sync # ~3 seconds (6-7x faster)

uv vs pip-tools

▼
bash
复制代码
# pip-tools pip-compile requirements.in pip-sync requirements.txt # ~15 seconds # uv uv lock uv sync --frozen # ~2 seconds (7-8x faster)

Common Workflows

Pattern 19: Starting a New Project

▼
bash
复制代码
# Complete workflow uv init my-project cd my-project # Set Python version uv python pin 3.12 # Add dependencies uv add fastapi uvicorn pydantic # Add dev dependencies uv add --dev pytest black ruff mypy # Create structure mkdir -p src/my_project tests # Run tests uv run pytest # Format code uv run black . uv run ruff check .

Pattern 20: Maintaining Existing Project

▼
bash
复制代码
# Clone repository git clone https://github.com/user/project.git cd project # Install dependencies (creates venv automatically) uv sync # Install with dev dependencies uv sync --all-extras # Update dependencies uv lock --upgrade # Run application uv run python app.py # Run tests uv run pytest # Add new dependency uv add new-package # Commit updated files git add pyproject.toml uv.lock git commit -m "Add new-package dependency"

Tool Integration

Pattern 21: Pre-commit Hooks

▼
yaml
复制代码
# .pre-commit-config.yaml repos: - repo: local hooks: - id: uv-lock name: uv lock entry: uv lock language: system pass_filenames: false - id: ruff name: ruff entry: uv run ruff check --fix language: system types: [python] - id: black name: black entry: uv run black language: system types: [python]

Pattern 22: VS Code Integration

▼
json
复制代码
// .vscode/settings.json { "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python", "python.terminal.activateEnvironment": true, "python.testing.pytestEnabled": true, "python.testing.pytestArgs": ["-v"], "python.linting.enabled": true, "python.formatting.provider": "black", "[python]": { "editor.defaultFormatter": "ms-python.black-formatter", "editor.formatOnSave": true } }

Troubleshooting

Common Issues

▼
bash
复制代码
# Issue: uv not found # Solution: Add to PATH or reinstall echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc # Issue: Wrong Python version # Solution: Pin version explicitly uv python pin 3.12 uv venv --python 3.12 # Issue: Dependency conflict # Solution: Check resolution uv lock --verbose # Issue: Cache issues # Solution: Clear cache uv cache clean # Issue: Lockfile out of sync # Solution: Regenerate uv lock --upgrade

Best Practices

Project Setup

  1. Always use lockfiles for reproducibility
  2. Pin Python version with .python-version
  3. Separate dev dependencies from production
  4. Use uv run instead of activating venv
  5. Commit uv.lock to version control
  6. Use --frozen in CI for consistent builds
  7. Leverage global cache for speed
  8. Use workspace for monorepos
  9. Export requirements.txt for compatibility
  10. Keep uv updated for latest features

Performance Tips

▼
bash
复制代码
# Use frozen installs in CI uv sync --frozen # Use offline mode when possible uv sync --offline # Parallel operations (automatic) # uv does this by default # Reuse cache across environments # uv shares cache globally # Use lockfiles to skip resolution uv sync --frozen # skips resolution

Migration Guide

From pip + requirements.txt

▼
bash
复制代码
# Before python -m venv .venv source .venv/bin/activate pip install -r requirements.txt # After uv venv uv pip install -r requirements.txt # Or better: uv init uv add -r requirements.txt

From Poetry

▼
bash
复制代码
# Before poetry install poetry add requests # After uv sync uv add requests # Keep existing pyproject.toml # uv reads [project] and [tool.poetry] sections

From pip-tools

▼
bash
复制代码
# Before pip-compile requirements.in pip-sync requirements.txt # After uv lock uv sync --frozen

Command Reference

Essential Commands

▼
bash
复制代码
# Project management uv init [PATH] # Initialize project uv add PACKAGE # Add dependency uv remove PACKAGE # Remove dependency uv sync # Install dependencies uv lock # Create/update lockfile # Virtual environments uv venv [PATH] # Create venv uv run COMMAND # Run in venv # Python management uv python install VERSION # Install Python uv python list # List installed Pythons uv python pin VERSION # Pin Python version # Package installation (pip-compatible) uv pip install PACKAGE # Install package uv pip uninstall PACKAGE # Uninstall package uv pip freeze # List installed uv pip list # List packages # Utility uv cache clean # Clear cache uv cache dir # Show cache location uv --version # Show version

Resources

  • Official documentation: https://docs.astral.sh/uv/
  • GitHub repository: https://github.com/astral-sh/uv
  • Astral blog: https://astral.sh/blog
  • Migration guides: https://docs.astral.sh/uv/guides/
  • Comparison with other tools: https://docs.astral.sh/uv/pip/compatibility/

Best Practices Summary

  1. Use uv for all new projects - Start with uv init
  2. Commit lockfiles - Ensure reproducible builds
  3. Pin Python versions - Use .python-version
  4. Use uv run - Avoid manual venv activation
  5. Leverage caching - Let uv manage global cache
  6. Use --frozen in CI - Exact reproduction
  7. Keep uv updated - Fast-moving project
  8. Use workspaces - For monorepo projects
  9. Export for compatibility - Generate requirements.txt when needed
  10. Read the docs - uv is feature-rich and evolving
软件开发

快捷安装

复制到终端去安装 Skill

npxskillsaddwshobson/agents--skill"uv-package-manager"
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI
Skills 推荐
debug
debug 是一个系统化定位软件缺陷根因的技能,适用于用户报告 'fix'、'broken'、'error' 等问题或测试意外失败时。它通过可验证的假设、最小复现、因果链分析和回归测试,确保在修复前准确定位根本原因。
retrieving-developer-knowledge
retrieving-developer-knowledge 用于搜索、获取和整合 Google 官方开发者文档,覆盖 Google Cloud、AI/Gemini、Android、Chrome、Web、Flutter、Go、Firebase 等平台,适用于查询 gcloud CLI 命令、API 语法、IAM 权限或架构对比等场景。
diff-intake
diff-intake 读取 PR 或分支差异,生成结构化 YAML 变更摘要,用于下游 analytics instrumentation 技能。适用于用户提交 PR 链接、分支对比或原始 diff 后需理解变更内容、评估分析覆盖或启动埋点流程的场景。
implement
实现 Linus Dashboard 的功能开发与集成,基于 TypeScript 和 Python 构建前后端组件,遵循严格的代码规范与架构模式,完成视图、卡片、服务及传感器等模块的创建与验证,确保高质量交付并兼容 Home Assistant 生态。
pypi-server
支持从源码构建 Python 软件包,并搭建本地 PyPI 服务,实现私有包的托管与分发,使团队可通过 pip 直接安装内部开发的模块。