uv format

格式化项目中的 Python 代码。

使用 Ruff 格式化器格式化 Python 代码。默认情况下，项目中的所有 Python 文件都会被格式化。此命令的行为与在项目根目录中运行 ruff format 相同。

要检查文件是否已格式化而不修改它们，请使用 --check。要查看格式化更改的差异，请使用 --diff。

可以在 -- 之后向 Ruff 传递额外的参数。

用法

uv format [OPTIONS] [-- <EXTRA_ARGS>...]

参数

EXTRA_ARGS

传递给 Ruff 的额外参数。

例如，使用 uv format -- --line-length 100 设置行长度，或使用 uv format -- src/module/foo.py 格式化特定文件。

选项

--allow-insecure-host, --trusted-host allow-insecure-host

允许与主机建立不安全连接。

可以多次提供。

预期接收主机名（例如 localhost）、主机-端口对（例如 localhost:8080）或 URL（例如 https://localhost）。

警告：此列表中的主机将不会根据系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --allow-insecure-host，因为它会绕过 SSL 验证，可能使您遭受中间人攻击（MITM）。

也可以通过 UV_INSECURE_HOST 环境变量设置。

--cache-dir cache-dir

缓存目录的路径。

在 macOS 和 Linux 上默认为 $XDG_CACHE_HOME/uv 或 $HOME/.cache/uv，在 Windows 上为 %LOCALAPPDATA%\uv\cache。

要查看缓存目录的位置，请运行 uv cache dir。

也可以通过 UV_CACHE_DIR 环境变量设置。

--check

检查文件是否已格式化，而不应用更改

--color color-choice

控制输出中颜色的使用。

默认情况下，uv 在写入终端时会自动检测是否支持颜色。

可能的值：

• auto：仅当输出发送到支持颜色的终端或 TTY 时启用彩色输出
• always：无论检测到的环境如何，始终启用彩色输出
• never：禁用彩色输出

--config-file config-file

用于配置的 uv.toml 文件的路径。

虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。

也可以通过 UV_CONFIG_FILE 环境变量设置。

--diff

显示格式化更改的差异，而不应用它们。

隐含 --check。

--directory directory

在运行命令之前切换到给定目录。

相对路径以给定目录为基准进行解析。

参见 --project 仅更改项目根目录。

也可以通过 UV_WORKING_DIR 环境变量设置。

--exclude-newer exclude-newer

将候选 Ruff 版本限制为在给定日期之前发布的版本。

接受 RFC 3339 的超集（例如 2006-12-02T02:07:43Z）或相同格式的本地日期（例如 2006-12-02），以及相对于"现在"的持续时间（例如 -1 week）。

也可以通过 UV_EXCLUDE_NEWER 环境变量设置。

--help, -h

显示此命令的简洁帮助信息

--managed-python

要求使用 uv 管理的 Python 版本 [env: UV_MANAGED_PYTHON=]

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果未安装 uv 管理的 Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

--no-cache, --no-cache-dir, -n

避免读取或写入缓存，而是在操作期间使用临时目录

也可以通过 UV_NO_CACHE 环境变量设置。

--no-config

避免发现配置文件（pyproject.toml、uv.toml）。

通常，配置文件会在当前目录、父目录或用户配置目录中被发现。

也可以通过 UV_NO_CONFIG 环境变量设置。

--no-managed-python

禁用 uv 管理的 Python 版本 [env: UV_NO_MANAGED_PYTHON=]

相反，uv 将在系统上搜索合适的 Python 版本。

--no-progress

隐藏所有进度输出 [env: UV_NO_PROGRESS=]

例如，旋转动画或进度条。

--no-project

避免发现项目或工作区。

不在当前项目的上下文中运行格式化器，而是在当前目录的上下文中运行。当当前目录不是项目时，这很有用。

也可以通过 UV_NO_PROJECT 环境变量设置。

--no-python-downloads

禁用自动下载 Python。

--offline

禁用网络访问 [env: UV_OFFLINE=]

禁用后，uv 将仅使用本地缓存的数据和本地可用的文件。

--project project

在给定目录中发现项目。

所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境（.venv）也是如此。

其他命令行参数（例如相对路径）将相对于当前工作目录进行解析。

参见 --directory 完全更改工作目录。

此设置在 uv pip 接口中使用时无效。

也可以通过 UV_PROJECT 环境变量设置。

--quiet, -q

使用静默输出。

重复此选项，例如 -qq，将启用静默模式，在此模式下 uv 不会向 stdout 写入任何输出。

--system-certs

是否从平台的本地证书存储加载 TLS 证书 [env: UV_SYSTEM_CERTS=]

默认情况下，uv 使用内置的 Mozilla 根证书，这提高了可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能希望使用平台的本地证书存储，特别是当您依赖系统证书存储中包含的企业信任根（例如用于强制代理）时。

--verbose, -v

使用详细输出。

您可以使用 RUST_LOG 环境变量配置细粒度的日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）

--version version

用于格式化的 Ruff 版本。

接受版本号（例如 0.8.2，将被视为精确锁定）、版本说明符（例如 >=0.8.0）或 latest 以使用最新可用版本。

默认情况下，将使用受约束的 Ruff 版本范围（例如 >=0.15,<0.16）。