跳转至

uv init

创建一个新项目。

遵循 pyproject.toml 规范。

如果目标位置已存在 pyproject.toml，uv 将报错退出。

如果在目标路径的任何父目录中找到 pyproject.toml，该项目将作为父项目的工作空间（workspace）成员添加。

某些项目状态在需要时才会创建，例如，项目虚拟环境（.venv）和锁文件（uv.lock）会在首次同步（sync）时延迟创建。

用法（Usage）

uv init [OPTIONS] [PATH]

参数（Arguments）

PATH

用于项目/脚本的路径。

初始化应用（app）或库（library）时默认为当前工作目录；初始化脚本（script）时为必需参数。接受相对路径和绝对路径。

如果在目标路径的任何父目录中找到 pyproject.toml，除非提供了 --no-workspace，否则该项目将作为父项目的 workspace 成员添加。

选项（Options）

--allow-insecure-host、--trusted-host allow-insecure-host

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

可以多次提供。

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

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

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

--app、--application

创建一个应用（application）项目。

如果未指定 --lib，这是默认行为。

此类项目适用于 Web 服务器、脚本和命令行接口。

默认情况下，应用不打算作为 Python 包构建和分发。可以使用 --package 选项创建可分发的应用，例如，如果您想通过 PyPI 分发命令行接口。

--author-from author-from

填充 pyproject.toml 中的 authors 字段。

默认情况下，uv 会尝试从某些来源（例如 Git）推断作者信息（auto）。使用 --author-from git 仅从 Git 配置推断。使用 --author-from none 则不推断作者信息。

可选值：

  • auto：从某些来源（例如 Git）自动获取作者信息
  • git：仅从 Git 配置获取作者信息
  • none：不推断作者信息
--bare

仅创建 pyproject.toml。

禁用创建额外文件，如 README.md、src/ 目录树、.python-version 文件等。

仅在与 --package 或 --build-backend 结合使用时才创建 [build-system] 表。

当与 --script 结合使用时，脚本将仅包含内联元数据头。

--build-backend build-backend

为项目初始化指定的构建后端（build-backend）。

隐式设置 --package。

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

可选值：

  • uv：使用 uv 作为项目构建后端
  • hatch：使用 hatchling 作为项目构建后端
  • flit：使用 flit-core 作为项目构建后端
  • pdm：使用 pdm-backend 作为项目构建后端
  • poetry：使用 poetry-core 作为项目构建后端
  • setuptools：使用 setuptools 作为项目构建后端
  • maturin：使用 maturin 作为项目构建后端
  • scikit：使用 scikit-build-core 作为项目构建后端
--cache-dir cache-dir

缓存目录的路径。

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

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

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

--color color-choice

控制输出中颜色的使用。

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

可选值：

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

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

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

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

--description description

设置项目描述

--directory directory

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

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

请参阅 --project 以仅更改项目根目录。

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

--help、-h

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

--lib、--library

创建一个库（library）项目。

库是一个旨在作为 Python 包构建和分发的项目。

--managed-python

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

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

--name name

项目名称。

默认为目录名称。

--no-cache、--no-cache-dir、-n

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

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

--no-config

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

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

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

--no-description

禁用项目描述

--no-managed-python

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

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

--no-package

不将项目设置为可作为 Python 包构建。

不为项目包含 [build-system]。

这是使用 --app 时的默认行为。

--no-pin-python

不为项目创建 .python-version 文件。

默认情况下，uv 会创建一个 .python-version 文件，其中包含所发现 Python 解释器的次要版本，这将导致后续 uv 命令使用该版本。

--no-progress

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

例如，旋转指示器（spinner）或进度条。

--no-python-downloads

禁用 Python 的自动下载。

--no-readme

不创建 README.md 文件

--no-workspace、--no-project

避免发现 workspace，创建一个独立项目。

默认情况下，uv 会在当前目录或任何父目录中搜索 workspace。

--offline

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

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

--package

将项目设置为可作为 Python 包构建。

为项目定义 [build-system]。

这是使用 --lib 或 --build-backend 时的默认行为，或者当 packaged-init 预览功能启用时。未来将无条件成为默认行为。

当与 --app 一起使用时，将包含 [project.scripts] 入口点并使用 src/ 项目结构。

--project project

在给定目录中发现项目。

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

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

请参阅 --directory 以完全更改工作目录。

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

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

--python、-p python

用于确定最低支持 Python 版本的 Python 解释器。

请参阅 uv python 以查看支持的请求格式。

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

--quiet、-q

使用静默输出。

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

--script

创建一个脚本。

脚本是一个独立文件，带有嵌入的元数据，枚举其依赖项以及任何 Python 版本要求，如 PEP 723 规范所定义。

PEP 723 脚本可以直接使用 uv run 执行。

默认情况下，添加对系统 Python 版本的要求；使用 --python 指定替代的 Python 版本要求。

--system-certs

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

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

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

--vcs vcs

为项目初始化版本控制系统。

默认情况下，uv 将初始化一个 Git 仓库（git）。使用 --vcs none 显式避免初始化版本控制系统。

可选值：

  • git：使用 Git 进行版本控制
  • none：不使用任何版本控制系统
--verbose、-v

使用详细输出。

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