uv-ruff-python-tools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UV & Ruff: Modern Python Development Tools

UV & Ruff：现代Python开发工具

Supercharge your Python development with Astral's blazing-fast tooling suite - uv for package management and ruff for code quality.

借助Astral的极速工具套件提升你的Python开发效率——uv用于包管理，ruff用于代码质量保障。

When to Use This Skill

何时使用该技能

Use this skill when you need to:

Package Management: Install, update, or manage Python dependencies 10-100x faster than pip
Project Setup: Initialize new Python projects with modern standards
Python Versions: Install and manage multiple Python versions
Code Linting: Check Python code for errors and style issues
Code Formatting: Auto-format Python code to consistent style
Virtual Environments: Create and manage isolated Python environments
Migration: Move from pip, conda, poetry, or pipx to modern tooling

在以下场景中使用本技能：

包管理：比pip快10-100倍的速度安装、更新或管理Python依赖项
项目初始化：按照现代标准创建新的Python项目
Python版本管理：安装并管理多个Python版本
代码检查：检测Python代码中的错误与风格问题
代码格式化：自动将Python代码格式化为统一风格
虚拟环境管理：创建并管理独立的Python环境
工具迁移：从pip、conda、poetry或pipx迁移至现代工具链

Quick Start

快速开始

Installing UV

安装UV

bash

undefined

bash

undefined

macOS/Linux - standalone installer

macOS/Linux - 独立安装器

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows - PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

With Homebrew

使用Homebrew

brew install uv

With pipx

使用pipx

pipx install uv

Verify installation

验证安装

uv version

undefined

uv version

undefined

Installing Ruff

安装Ruff

bash

undefined

bash

undefined

With uv (recommended)

With pip

使用pip安装

pip install ruff

With Homebrew

使用Homebrew安装

brew install ruff

Verify installation

验证安装

ruff version

undefined

ruff version

undefined

Common Workflows

常见工作流

Project Management with UV

使用UV进行项目管理

bash

undefined

bash

undefined

Create a new project

创建新项目

uv init my-project cd my-project

Add dependencies

添加依赖项

uv add requests pandas numpy

Add development dependencies

添加开发依赖项

uv add --dev pytest black ruff

Install all dependencies

安装所有依赖项

uv sync

Run a script in the project environment

在项目环境中运行脚本

uv run python main.py

Run a tool (like pytest)

运行工具（如pytest）

uv run pytest

Update dependencies

更新依赖项

uv lock --upgrade uv sync

undefined

uv lock --upgrade uv sync

undefined

Code Quality with Ruff

使用Ruff保障代码质量

bash

undefined

bash

undefined

Check for linting errors

检查代码中的错误

ruff check .

Auto-fix linting errors

自动修复代码错误

ruff check --fix .

Format code

格式化代码

ruff format .

Check formatting without changes

检查代码格式但不修改

ruff format --check .

Watch mode (continuous linting)

监听模式（持续检查）

ruff check --watch

Lint and format in one command

一键完成代码检查与格式化

ruff check --fix . && ruff format .

undefined

ruff check --fix . && ruff format .

undefined

Python Version Management

Python版本管理

bash

undefined

bash

undefined

Install Python versions

安装指定Python版本

uv python install 3.11 3.12 3.13

List installed Python versions

列出已安装的Python版本

uv python list

Pin Python version for project

为项目固定Python版本

uv python pin 3.12

Use specific Python version

使用指定Python版本运行脚本

uv run --python 3.11 python script.py

undefined

uv run --python 3.11 python script.py

undefined

Key Features

核心特性

UV Features

UV特性

🚀 Speed: 10-100x faster than pip for package installation

Parallel downloads and caching
Rust-powered dependency resolution
Global package cache for deduplication

📦 All-in-One Tool: Replaces multiple tools

```
pip
```
- Package installation
```
pip-tools
```
- Dependency locking
```
pipx
```
- Tool installation
```
poetry
```
- Project management
```
pyenv
```
- Python version management
```
virtualenv
```
- Environment creation

🔒 Reproducible Environments:

Universal lockfiles (
```
uv.lock
```
)
Platform-independent resolution
Version pinning

🚀 极速性能：包安装速度比pip快10-100倍

并行下载与缓存机制
Rust驱动的依赖解析
全局包缓存实现重复数据删除

📦 一站式工具：替代多款工具

```
pip
```
- 包安装
```
pip-tools
```
- 依赖锁定
```
pipx
```
- 工具安装
```
poetry
```
- 项目管理
```
pyenv
```
- Python版本管理
```
virtualenv
```
- 环境创建

🔒 可复现环境：

通用锁文件（
```
uv.lock
```
）
跨平台依赖解析
版本固定

Ruff Features

Ruff特性

⚡ Extreme Speed: 10-100x faster than existing linters

Written in Rust for maximum performance
Processes entire codebases in milliseconds

🔧 Unified Tool: Replaces multiple tools

```
Flake8
```
- Linting
```
Black
```
- Formatting
```
isort
```
- Import sorting
```
pyupgrade
```
- Modern Python syntax
```
autoflake
```
- Unused code removal

📏 800+ Rules: Comprehensive code quality

Pyflakes error detection
pycodestyle (PEP 8) compliance
flake8-bugbear best practices
Many popular Flake8 plugins built-in

⚡ 极致速度：比现有代码检查工具快10-100倍

基于Rust开发，性能拉满
毫秒级处理整个代码库

🔧 一体化工具：替代多款工具

```
Flake8
```
- 代码检查
```
Black
```
- 代码格式化
```
isort
```
- 导入排序
```
pyupgrade
```
- Python语法现代化
```
autoflake
```
- 移除未使用代码

📏 800+规则：全面的代码质量保障

Pyflakes错误检测
pycodestyle（PEP 8）合规性检查
flake8-bugbear最佳实践
内置多款热门Flake8插件

Common Patterns

常见使用模式

UV Patterns

UV使用模式

bash

undefined

bash

undefined

Quick tool execution (like npx or pipx)

快速执行工具（类似npx或pipx）

uvx ruff check . uvx black . uvx pytest

Build and publish packages

构建并发布包

uv build uv publish

Pip-compatible interface (drop-in replacement)

兼容pip的接口（直接替代）

uv pip install requests uv pip freeze > requirements.txt uv pip compile requirements.in uv pip sync requirements.txt

Create virtual environment

创建虚拟环境

uv venv source .venv/bin/activate # Linux/macOS .venv\Scripts\activate # Windows

Run scripts with inline dependencies

运行包含依赖项的脚本

uv add --script my_script.py requests uv run my_script.py

undefined

uv add --script my_script.py requests uv run my_script.py

undefined

Ruff Patterns

Ruff使用模式

bash

undefined

bash

undefined

Enable specific rule sets

启用特定规则集

ruff check --select E,W,F,I .

Ignore specific rules

忽略特定规则

ruff check --ignore E501 .

Show fixes that will be applied

显示即将应用的修复内容

ruff check --diff .

Format with preview features

使用预览特性格式化代码

ruff format --preview .

Check specific files

检查指定文件

ruff check src/main.py tests/test_main.py

Output formats

输出格式设置

ruff check --output-format json . ruff check --output-format github .

undefined

ruff check --output-format json . ruff check --output-format github .

undefined

Configuration

配置说明

UV Configuration (pyproject.toml)

UV配置（pyproject.toml）

toml

[project]
name = "my-project"
version = "0.1.0"
description = "My Python project"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31.0",
    "pandas>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "ruff>=0.1.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
    "ruff>=0.1.0",
]

[tool.uv.sources]

toml

[project]
name = "my-project"
version = "0.1.0"
description = "My Python project"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31.0",
    "pandas>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "ruff>=0.1.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
    "ruff>=0.1.0",
]

[tool.uv.sources]

Use specific package sources if needed

按需配置特定包源

undefined

undefined

Ruff Configuration (pyproject.toml)

Ruff配置（pyproject.toml）

toml

[tool.ruff]

toml

[tool.ruff]

Set line length

设置行长度

line-length = 88 indent-width = 4 target-version = "py311"

Exclude directories

排除目录

exclude = [ ".git", ".venv", "pycache", "build", "dist", ]

[tool.ruff.lint]

exclude = [ ".git", ".venv", "pycache", "build", "dist", ]

[tool.ruff.lint]

Enable rule sets

启用规则集

select = [ "E", # pycodestyle errors "W", # pycodestyle warnings "F", # Pyflakes "I", # isort "B", # flake8-bugbear "UP", # pyupgrade ]

select = [ "E", # pycodestyle错误 "W", # pycodestyle警告 "F", # Pyflakes "I", # isort "B", # flake8-bugbear "UP", # pyupgrade ]

Ignore specific rules

忽略特定规则

ignore = [ "E501", # line too long (handled by formatter) ]

ignore = [ "E501", # 行过长（由格式化工具处理） ]

Allow auto-fix for all enabled rules

允许自动修复所有启用的规则

fixable = ["ALL"] unfixable = []

[tool.ruff.lint.per-file-ignores] "init.py" = ["F401"] # Allow unused imports "tests/*" = ["S101"] # Allow assert statements

[tool.ruff.format] quote-style = "double" indent-style = "space" line-ending = "auto"

undefined

fixable = ["ALL"] unfixable = []

[tool.ruff.lint.per-file-ignores] "init.py" = ["F401"] # 允许未使用的导入 "tests/*" = ["S101"] # 允许assert语句

[tool.ruff.format] quote-style = "double" indent-style = "space" line-ending = "auto"

undefined

Integration with Development Tools

与开发工具集成

Pre-commit Hooks

预提交钩子

yaml

undefined

yaml

undefined

.pre-commit-config.yaml

repos:

repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.12.8 hooks:
- id: ruff args: [--fix]
- id: ruff-format

undefined

repos:

repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.12.8 hooks:
- id: ruff args: [--fix]
- id: ruff-format

undefined

CI/CD (GitHub Actions)

CI/CD（GitHub Actions）

yaml

name: Lint and Test

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh

      - name: Install dependencies
        run: uv sync

      - name: Lint with ruff
        run: uv run ruff check .

      - name: Format check with ruff
        run: uv run ruff format --check .

      - name: Run tests
        run: uv run pytest

yaml

name: Lint and Test

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh

      - name: Install dependencies
        run: uv sync

      - name: Lint with ruff
        run: uv run ruff check .

      - name: Format check with ruff
        run: uv run ruff format --check .

      - name: Run tests
        run: uv run pytest

Detailed Documentation

详细文档

For comprehensive guides and advanced usage, see the reference files:

references/uv-guide.md - Complete uv documentation
- Project management workflows
- Python version management
- Package building and publishing
- Migration from other tools
references/ruff-guide.md - Complete ruff documentation
- All 800+ linting rules
- Formatting options
- Rule configuration
- Editor integration
references/migration.md - Migration guides
- From pip + virtualenv
- From conda
- From poetry
- From pipx
references/workflows.md - Advanced workflows
- Monorepo management
- Docker integration
- Production deployments

如需全面指南与高级用法，请参考以下参考文档：

references/uv-guide.md - 完整UV文档
- 项目管理工作流
- Python版本管理
- 包构建与发布
- 从其他工具迁移
references/ruff-guide.md - 完整Ruff文档
- 全部800+检查规则
- 格式化选项
- 规则配置
- 编辑器集成
references/migration.md - 迁移指南
- 从pip + virtualenv迁移
- 从conda迁移
- 从poetry迁移
- 从pipx迁移
references/workflows.md - 高级工作流
- 单体仓库管理
- Docker集成
- 生产环境部署

Resources

资源链接

Official Documentation:

GitHub Repositories:

Community:

官方文档：

GitHub仓库：

社区支持：

Troubleshooting

故障排查

UV Issues:

bash

undefined

UV问题：

bash

undefined

Clear cache

清理缓存

uv cache clean

Reinstall Python

重新安装Python

rm -r "$(uv python dir)" uv python install 3.12

Reset lockfile

重置锁文件

rm uv.lock uv lock


**Ruff Issues:**
```bash

rm uv.lock uv lock


**Ruff问题：**
```bash

Clear cache

清理缓存

ruff clean

Show current settings

显示当前设置

ruff check --show-settings

List all available rules

列出所有可用规则

ruff rule --all

Explain a specific rule

解释特定规则

ruff rule E501

undefined

ruff rule E501

undefined

Notes

注意事项

UV and Ruff are both built by Astral and designed to work together seamlessly
UV automatically creates and manages virtual environments - no manual activation needed
Ruff can replace Black, isort, Flake8, and more with a single tool
Both tools are written in Rust for maximum performance
UV's lockfile format is becoming a Python standard (PEP 751 proposal)
Ruff is compatible with Black formatting by default

UV与Ruff均由Astral开发，设计为无缝协作
UV自动创建并管理虚拟环境，无需手动激活
Ruff可通过单一工具替代Black、isort、Flake8等多款工具
两款工具均基于Rust开发，性能拉满
UV的锁文件格式正在成为Python标准（PEP 751提案）
Ruff默认与Black格式化规则兼容

uv-ruff-python-tools

Original

Translation

UV & Ruff: Modern Python Development Tools

UV & Ruff：现代Python开发工具

When to Use This Skill

何时使用该技能

Quick Start

快速开始

Installing UV

安装UV

macOS/Linux - standalone installer

macOS/Linux - 独立安装器

Windows - PowerShell

Windows - PowerShell

With Homebrew

使用Homebrew

With pipx

使用pipx

Verify installation

验证安装

Installing Ruff

安装Ruff

With uv (recommended)

推荐使用uv安装

With pip

使用pip安装

With Homebrew

使用Homebrew安装

Verify installation

验证安装

Common Workflows

常见工作流

Project Management with UV

使用UV进行项目管理

Create a new project

创建新项目

Add dependencies

添加依赖项

Add development dependencies

添加开发依赖项

Install all dependencies

安装所有依赖项

Run a script in the project environment

在项目环境中运行脚本

Run a tool (like pytest)

运行工具（如pytest）

Update dependencies

更新依赖项

Code Quality with Ruff

使用Ruff保障代码质量

Check for linting errors

检查代码中的错误

Auto-fix linting errors

自动修复代码错误

Format code

格式化代码

Check formatting without changes

检查代码格式但不修改

Watch mode (continuous linting)

监听模式（持续检查）

Lint and format in one command

一键完成代码检查与格式化

Python Version Management

Python版本管理

Install Python versions

安装指定Python版本

List installed Python versions

列出已安装的Python版本

Pin Python version for project

为项目固定Python版本

Use specific Python version

使用指定Python版本运行脚本

Key Features

核心特性

UV Features

UV特性

Ruff Features

Ruff特性

Common Patterns