Ruff 安装完全指南从 uvx 零安装、pip/uv 包管理到 Docker 容器化的全平台部署【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruffRuff 是一个用 Rust 编写的极速 Python 代码检查器linter与格式化器formatter它同时支持 lintruff check与格式检查ruff format两条核心命令线。本指南以官方 docs/installation.md 为主线系统梳理 Ruff 在 PyPI、uv/pip/pipx、独立安装脚本、Homebrew、Conda、Docker 等各发行渠道的安装方式与适用场景并结合本仓库源码说明 Python 包封装、容器镜像结构等底层机制帮助你根据团队与运行环境选择最合适的部署方案。一、发行形态与版本概览Ruff 是一个单一静态二进制程序其核心 CLI 位于 crates/ruff对应的Cargo.toml声明当前版本为0.16.6并指定default-run ruff见 crates/ruff/Cargo.toml。正因为编译产物只是一个可执行文件Ruff 才能以极低的运行时依赖被分发到几乎每一种包管理器与容器环境中。从本仓库的工作区配置Cargo.toml可以看到Ruff 的源码按功能拆分为 40 余个 crate例如负责 lint 规则的ruff_linter、负责格式化引擎的ruff_python_formatter、负责语义分析的ruff_python_semantic等用户最终拿到的是 crates/ruff/src/main.rs 中main()所驱动的统一 CLI 入口。这种「内部模块化、外部单二进制」的架构正是官方文档中「一个二进制全平台可用」这一安装哲学的实现基础。二、通过 PyPI 安装uv / pip / pipx / uvxRuff 以ruff为包名发布在 PyPI 上因此任何 Python 生态的包管理器都可以安装它。官方文档给出了四种方式覆盖「全局安装」「项目内安装」与「零安装直接调用」三种使用场景。1. uvx无需安装的直接调用推荐体验方式uvx是 uv 自带的「在隔离环境中运行工具」命令它会在需要时自动获取对应版本的 Ruff而不修改你当前的环境。官方文档示例uvx ruff0.16.6 check # Lint all files in the current directory. uvx ruff0.16.6 format # Format all files in the current directory.这里ruff0.16.6显式锁定了与当前仓库一致的版本号参见 crates/ruff/Cargo.toml 中version 0.16.6。如果不带版本号uvx ruff则会解析为最新可用版本。uvx适合 CI 流水线或临时脚本中「即用即走」的场景不污染任何环境。2. uv tool install全局安装官方推荐$ # Install Ruff globally. $ uv tool install rufflatestuv tool install会将 Ruff 安装为一个独立的全局工具二进制会放入 uv 管理的工具目录并在 PATH 中提供ruff命令。这是官方文档标注为recommended的全局安装方式后续uv tool upgrade ruff即可平滑升级。3. uv add --dev作为项目开发依赖$ # Or add Ruff to your project. $ uv add --dev ruff该命令会把ruff写入项目的pyproject.toml开发依赖[dependency-groups]或 dev 依赖区之后通过uv run ruff check调用确保团队所有成员使用锁定的同一版本。这与 Ruff 自身在 pyproject.toml 中管理自身依赖的方式一致适合「lint/format 结果可复现」的团队协作诉求。4. pip 与 pipx经典 Python 安装方式$ # With pip. $ pip install ruff $ # With pipx. $ pipx install ruffpip install ruff会把ruff可执行文件放入当前 Python 环境的binUnix或ScriptsWindows目录。pipx则把 Ruff 隔离安装在独立虚拟环境中避免与项目依赖互相污染适合「全局工具」定位。Python 包是如何转发到二进制程序的从源码看PyPI 上的ruff并不仅仅是二进制分发仓库中的 python/ruff/init.py 与 python/ruff/_find_ruff.py 实现了一个二进制定位器。find_ruff_bin()会按顺序在以下位置查找名为ruffWindows 上带.exe后缀的可执行文件当前 Python 的 scripts 目录sysconfig.get_path(scripts)base prefix 对应的 scripts 目录包目录向上匹配Lib/site-packages/ruffWindows或lib/python*/site-packages/ruffUnix后拼接出的Scripts/bin目录与包目录相邻的bin目录对应pip install --target场景用户 scheme 的 scripts 目录如~/.local/bin。若都找不到会抛出RuffNotFound并列出全部已探测路径见 python/ruff/_find_ruff.py。而 python/ruff/main.py 使得python -m ruff同样可用Unix 下通过os.execvp直接替换为 ruff 进程Windows 下则用subprocess.run透传参数并透出退出码。因此无论你是ruff check、uvx ruff check还是python -m ruff check最终都进入同一个 Rust CLI 入口 crates/ruff/src/main.rs。三、独立安装脚本一条命令装好自 0.5.0 起从0.5.0版本开始Ruff 官方提供独立安装脚本无需任何 Python 环境或包管理器适合服务器、Docker 基础镜像或 CI runner 上的快速部署$ # On macOS and Linux. $ curl -LsSf https://astral.sh/ruff/install.sh | sh $ # On Windows. $ powershell -c irm https://astral.sh/ruff/install.ps1 | iex $ # For a specific version. $ curl -LsSf https://astral.sh/ruff/0.5.0/install.sh | sh $ powershell -c irm https://astral.sh/ruff/0.5.0/install.ps1 | iex安装脚本会检测平台架构从官方发布渠道下载对应版本的预编译二进制并放入用户级 bin 目录。指定版本时把 URL 中的版本段替换为目标版本即可例如https://astral.sh/ruff/0.16.6/install.sh。四、系统包管理器安装融入既有运维体系对于已经用系统包管理器管理开发工具链的环境Ruff 官方文档列出了多条官方维护的渠道可按发行版直接选用。Homebrew / LinuxbrewmacOS、Linux$ brew install ruffRuff 已收录于 Homebrew 官方 formulamacOS 与 Linuxbrew 用户均可使用。Condaconda-forge$ conda install -c conda-forge ruffRuff 在conda-forge渠道发布适合以 Conda 作为主包管理器的数据科学环境。pkgx$ pkgx install ruffpkgx 是一个无需 root 的工具运行时pkgx install ruff会将其安装到 pkgx 管理的工具目录中。Arch Linux官方仓库$ pacman -S ruffRuff 位于 Arch 官方 extra 仓库直接pacman -S ruff即可。Alpine Linux社区仓库$ apk add ruffAlpine 社区仓库提供了ruff包注意 Alpine 默认使用 musl libc官方预编译二进制本身也包含 musl 目标见下文 Docker 一节对x86_64-unknown-linux-musl的说明因此兼容性良好。openSUSE Tumbleweed$ sudo zypper install python3-ruffopenSUSE Tumbleweed 发行仓库中的软件包名为python3-ruff需要sudo执行zypper install。提示通过系统包管理器安装的版本可能滞后于 PyPI 上的最新版本。若对版本敏感建议优先使用 uv/pipx 或独立安装脚本。五、Docker 容器化部署Ruff 官方在 GHCR 上发布容器镜像ghcr.io/astral-sh/ruff每个发布版本打一个 tag另有一个latesttag 跟随最新版本$ docker run -v .:/io --rm ghcr.io/astral-sh/ruff check $ docker run -v .:/io --rm ghcr.io/astral-sh/ruff:0.3.0 check $ # Or, for Podman on SELinux. $ docker run -v .:/io:Z --rm ghcr.io/astral-sh/ruff check三条命令的含义-v .:/io把当前目录挂载到容器内的/io--rm容器退出后自动删除check在容器内对/io即宿主机当前目录执行 lint:0.3.0指定历史版本 tag:Z在 SELinux 启用的 Podman 主机上为挂载卷打上正确的 SELinux 标签否则容器可能没有读取卷的权限。镜像结构可以从仓库根目录的 Dockerfile 中得到印证该文件使用多阶段构建先在ubuntu构建阶段通过cargo zigbuild以*-unknown-linux-musl目标交叉编译出ruff二进制arm64 对应aarch64-unknown-linux-muslamd64 对应x86_64-unknown-linux-musl最终阶段基于scratch——即不含任何操作系统组件与 shell 的空白镜像只拷贝ruff可执行文件并将工作目录设为/io、ENTRYPOINT指向/ruff。这正是docker run ... ghcr.io/astral-sh/ruff check中check会成为 ruff 第一个参数的机制来源。由于镜像基于scratch它只适合作为命令行工具运行无法在容器内执行 shell 命令如需调试或封装脚本可以docker run时自行覆盖入口或在自定义镜像中COPY --fromghcr.io/astral-sh/ruff /ruff /usr/local/bin/ruff复用该二进制。六、安装后的验证与常用命令无论通过哪种渠道安装安装完成后都可以在命令行直接使用$ ruff check # Lint all files in the current directory. $ ruff format # Format all files in the current directory.ruff check对当前目录递归执行 lint输出规则代码与建议若项目存在pyproject.toml或ruff.toml会自动读取其中的 Ruff 配置段。ruff format对当前目录的 Python 文件执行格式化输出「已重写/未改动」的统计。建议安装后用ruff --version确认版本号。版本信息的格式化逻辑在 crates/ruff/src/version.rs日常发行版直接显示CARGO_PKG_VERSION如0.16.6若从 git 检出构建且存在提交信息则会显示形如0.16.63 (abc1234 2026-09-01)的格式其中3表示距离最近 tag 的提交数。此外Ruff 的 CLI 支持多种全局选项例如--config可指向 TOML 配置文件也可直接传line-length 100这样的键值覆盖、--isolated忽略所有配置文件等这些选项在 crates/ruff/src/args.rs 中定义并由 clap 解析。若需为编辑器或脚本生成 shell 补全可查看ruff generate-shell-completion对应 crates/ruff/src/commands/completions。七、从源码构建进阶Ruff 是一个 Cargo workspaceCargo.toml要求 Rust 工具链版本不低于1.96见工作区rust-version声明。从源码构建 ruff 二进制的方式$ cargo build --release --bin ruff构建产物位于target/release/ruff。仓库还提供了面向性能调优的构建脚本 scripts/build_ruff_pgo.py它使用「钉住的生态项目」对 Ruff 做 Profile-Guided OptimizationPGO构建适合对 lint 性能有极致要求的自建发行场景。对 WebAssembly 有需求的读者可以关注 crates/ruff_wasm它以 wasm-bindgen 导出 lint 与 format 核心能力见 crates/ruff_wasm/src/lib.rs是官方 Playground 的底层依赖不过这属于集成级能力常规安装无需涉及。八、安装方式速查与选型建议场景命令备注临时体验 / CI 即用即走uvx ruff0.16.6 check不落盘安装隔离执行全局安装推荐uv tool install rufflatestuv 托管便于升级项目开发依赖uv add --dev ruff版本随项目锁定经典 Python 环境pip install ruff装进当前 Python 环境隔离全局工具pipx install ruff独立虚拟环境免依赖快速安装curl -LsSf https://astral.sh/ruff/install.sh \| shmacOS/LinuxWindows 用 PowerShell 脚本macOS/Linuxbrew install ruffHomebrew/LinuxbrewConda 生态conda install -c conda-forge ruffconda-forge 渠道pkgxpkgx install ruff免 root 工具运行时Arch Linuxpacman -S ruff官方 extra 仓库Alpineapk add ruff社区仓库musl 兼容openSUSE Tumbleweedsudo zypper install python3-ruff发行仓库需 sudo容器化docker run -v .:/io --rm ghcr.io/astral-sh/ruff check基于 scratch 的静态镜像选型建议个人开发机优先uv tool install或pipx项目团队用uv add --dev锁定版本CI 与服务器用独立安装脚本或 Docker 镜像以系统包管理器为统一标准的团队则直接用对应发行版渠道。无论哪种方式Ruff 都保持「单一二进制 一致 CLI」的形态切换安装渠道不会带来行为差异。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考