uv venv
创建一个虚拟环境。
默认情况下，会在工作目录中创建一个名为 .venv 的虚拟环境。也可以通过位置参数提供替代路径。
如果在项目中，可以通过 UV_PROJECT_ENVIRONMENT 环境变量更改默认环境名称；此设置仅在从项目根目录运行时生效。
如果目标路径已存在虚拟环境，它将被删除，然后创建一个新的空虚拟环境。
使用 uv 时，无需手动激活虚拟环境。uv 会在工作目录或其任意父目录中查找虚拟环境（名为 .venv）。
用法（Usage）
参数（Arguments）
PATH要创建的虚拟环境的路径。
默认为工作目录中的
.venv。相对路径将相对于工作目录进行解析。
选项（Options）
--allow-existing保留目标路径中已存在的任何文件或目录。
默认情况下，如果给定路径非空，
uv venv将报错退出。--allow-existing选项则会直接写入给定路径，无论其内容如何，且不会事先清空。警告：如果现有虚拟环境与新创建的虚拟环境链接到不同的 Python 解释器，此选项可能导致意外行为。
--allow-insecure-host,--trusted-hostallow-insecure-host允许与主机的非安全连接。
可以多次指定。
期望接收主机名（例如
localhost）、主机-端口对（例如localhost:8080）或 URL（例如https://localhost）。警告：此列表中的主机将不会根据系统证书存储进行验证。仅在安全网络中使用
--allow-insecure-host并确保来源已验证，因为它绕过了 SSL 验证，可能使您面临中间人攻击（MITM）的风险。也可以通过
UV_INSECURE_HOST环境变量设置。--cache-dircache-dir缓存目录的路径。
在 macOS 和 Linux 上默认为
$XDG_CACHE_HOME/uv或$HOME/.cache/uv，在 Windows 上默认为%LOCALAPPDATA%\uv\cache。要查看缓存目录的位置，请运行
uv cache dir。也可以通过
UV_CACHE_DIR环境变量设置。--clear,-c删除目标路径中已存在的任何文件或目录 [env: UV_VENV_CLEAR=]
默认情况下，如果给定路径非空，
uv venv将报错退出。--clear选项则会在创建新虚拟环境之前清空非空路径。--colorcolor-choice控制输出中颜色的使用。
默认情况下，uv 会在写入终端时自动检测是否支持颜色。
可选值：
auto：仅当输出到支持颜色的终端或 TTY 时启用彩色输出always：无论检测到的环境如何，始终启用彩色输出never：禁用彩色输出
--config-fileconfig-file用于配置的
uv.toml文件路径。虽然 uv 配置可以包含在
pyproject.toml文件中，但在此上下文中不允许这样做。也可以通过
UV_CONFIG_FILE环境变量设置。--default-indexdefault-index默认包索引的 URL（默认为 https://pypi.org/simple）。
接受符合 PEP 503（简单仓库 API）的仓库，或按相同格式组织的本地目录。
通过此标志指定的索引的优先级低于通过
--index标志指定的所有其他索引。也可以通过
UV_DEFAULT_INDEX环境变量设置。--directorydirectory在运行命令之前切换到给定目录。
相对路径以给定目录为基准进行解析。
参见
--project以仅更改项目根目录。也可以通过
UV_WORKING_DIR环境变量设置。--exclude-newerexclude-newer将候选包限制为在给定日期之前上传的版本。
日期与每个单独分发构件（即每个文件上传到包索引的时间）的上传时间进行比较，而非包版本的发布日期。
接受 RFC 3339 时间戳（例如
2006-12-02T02:07:43Z）、相同格式的本地日期（例如2006-12-02，基于系统配置的时区解析）、"友好"时长（例如24 hours、1 week、30 days）或 ISO 8601 时长（例如PT24H、P7D、P30D）。时长不遵循本地时区的语义，始终按固定秒数解析，假设一天为 24 小时（例如，忽略夏令时转换）。不允许使用月和年等日历单位。
也可以通过
UV_EXCLUDE_NEWER环境变量设置。--exclude-newer-packageexclude-newer-package将特定包的候选版本限制为在给定日期之前上传的版本。
接受
PACKAGE=DATE格式的包-日期对，其中DATE是 RFC 3339 时间戳（例如2006-12-02T02:07:43Z）、相同格式的本地日期（例如2006-12-02，基于系统配置的时区解析）、"友好"时长（例如24 hours、1 week、30 days）或 ISO 8601 时长（例如PT24H、P7D、P30D）。时长不遵循本地时区的语义，始终按固定秒数解析，假设一天为 24 小时（例如，忽略夏令时转换）。不允许使用月和年等日历单位。
可以为不同的包多次指定。
--extra-index-urlextra-index-url（已弃用：请改用
--index）除--index-url之外要使用的额外包索引 URL。接受符合 PEP 503（简单仓库 API）的仓库，或按相同格式组织的本地目录。
通过此标志提供的所有索引的优先级高于
--index-url指定的索引（默认为 PyPI）。当提供多个--extra-index-url标志时，先指定的值优先级更高。也可以通过
UV_EXTRA_INDEX_URL环境变量设置。--find-links,-ffind-links除注册表索引中的内容外，用于搜索候选分发包的位置。
如果是路径，目标必须是一个目录，其中顶层包含作为 wheel 文件（
.whl）或源码分发包（例如.tar.gz或.zip）的包。如果是 URL，页面必须包含指向符合上述格式的包文件的扁平链接列表。
也可以通过
UV_FIND_LINKS环境变量设置。--force允许
--clear删除非虚拟环境目录。这将删除目标路径中的所有文件和目录。
--help,-h显示此命令的简明帮助信息
--indexindex解析依赖时使用的 URL，作为默认索引的补充。
接受符合 PEP 503（简单仓库 API）的仓库，或按相同格式组织的本地目录。
通过此标志提供的所有索引的优先级高于
--default-index指定的索引（默认为 PyPI）。当提供多个--index标志时，先指定的值优先级更高。不支持将索引名称作为值。相对路径必须使用
./或../（Unix）或.\\、..\\、./或../（Windows）来与索引名称区分。也可以通过
UV_INDEX环境变量设置。--index-strategyindex-strategy针对多个索引 URL 进行解析时使用的策略。
默认情况下，uv 会在第一个找到给定包的索引处停止，并将解析范围限制为该第一个索引上存在的版本（
first-index）。这可以防止"依赖混淆"（dependency confusion）攻击，即攻击者可以在替代索引上上传同名恶意包。也可以通过
UV_INDEX_STRATEGY环境变量设置。可选值：
first-index：仅使用为给定包名返回匹配结果的第一个索引的结果unsafe-first-match：在所有索引中搜索每个包名，在移至下一个索引之前穷尽第一个索引的版本unsafe-best-match：在所有索引中搜索每个包名，优先选择找到的"最佳"版本。如果一个包版本存在于多个索引中，则仅查看第一个索引中的条目
--index-url,-iindex-url（已弃用：请改用
--default-index）Python 包索引的 URL（默认为 https://pypi.org/simple）。接受符合 PEP 503（简单仓库 API）的仓库，或按相同格式组织的本地目录。
通过此标志指定的索引的优先级低于通过
--extra-index-url标志指定的所有其他索引。也可以通过
UV_INDEX_URL环境变量设置。--keyring-providerkeyring-provider尝试使用
keyring进行索引 URL 的身份验证。目前仅支持
--keyring-provider subprocess，它配置 uv 使用keyringCLI 来处理身份验证。默认为
disabled。也可以通过
UV_KEYRING_PROVIDER环境变量设置。可选值：
disabled：不使用 keyring 进行凭据查找subprocess：使用keyring命令进行凭据查找
--link-modelink-mode从全局缓存安装包时使用的方法。
此选项仅用于安装种子包（seed packages）。
在 macOS 和 Linux 上默认为
clone（也称为写时复制 Copy-on-Write），在 Windows 上默认为hardlink。警告：不鼓励使用符号链接（symlink）模式，因为它会在缓存和目标环境之间建立紧密耦合。例如，清除缓存（
uv cache clean）将通过删除底层源文件来破坏所有已安装的包。请谨慎使用符号链接。也可以通过
UV_LINK_MODE环境变量设置。可选值：
clone：从源克隆（即写时复制）包到目标copy：从源复制包到目标hardlink：从源硬链接包到目标symlink：从源符号链接包到目标
--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-index忽略注册表索引（例如 PyPI），转而依赖直接 URL 依赖和通过
--find-links提供的依赖--no-managed-python禁用 uv 管理的 Python 版本 [env: UV_NO_MANAGED_PYTHON=]
相反，uv 将在系统上搜索合适的 Python 版本。
--no-progress隐藏所有进度输出 [env: UV_NO_PROGRESS=]
例如，旋转指示器或进度条。
--no-project,--no-workspace避免发现项目或工作区。
默认情况下，uv 会在当前目录或任意父目录中搜索项目，以确定虚拟环境的默认路径并检查 Python 版本约束（如有）。
也可以通过
UV_NO_PROJECT环境变量设置。--no-python-downloads禁用 Python 的自动下载。
--offline禁用网络访问 [env: UV_OFFLINE=]
禁用后，uv 将仅使用本地缓存数据和本地可用文件。
--projectproject在给定目录中发现项目。
所有
pyproject.toml、uv.toml和.python-version文件将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境（.venv）也将同样被发现。其他命令行参数（如相对路径）将相对于当前工作目录进行解析。
参见
--directory以完全更改工作目录。此设置在
uv pip接口中使用时无效。也可以通过
UV_PROJECT环境变量设置。--promptprompt为虚拟环境提供替代的提示符前缀。
默认情况下，提示符取决于是否向
uv venv提供了路径。如果提供了路径（例如uv venv project），提示符将设置为目录名。如果未提供路径（uv venv），提示符将设置为当前目录的名称。如果提供了
"."，则无论是否向uv venv提供了路径，都将使用当前目录名。--python,-ppython用于虚拟环境的 Python 解释器。
在虚拟环境创建期间，uv 不会在虚拟环境中查找 Python 解释器。
有关 Python 发现和支持的请求格式的详细信息，请参见 uv python。
也可以通过
UV_PYTHON环境变量设置。--quiet,-q使用静默输出。
重复此选项，例如
-qq，将启用静默模式，在此模式下 uv 不会向 stdout 写入任何输出。--refresh刷新所有缓存数据
--refresh-packagerefresh-package刷新特定包的缓存数据
--relocatable使虚拟环境可重定位 [env: UV_VENV_RELOCATABLE=]
可重定位的虚拟环境可以移动和重新分发，而不会使其关联的入口点（entrypoint）和激活脚本失效。
请注意，这仅对标准的
console_scripts和gui_scripts能保证。如果其他脚本带有通用的#!python[w]shebang，则可能会被调整，而二进制文件则保持原样。由于使环境可重定位（通过写入相对路径而非绝对路径），入口点和脚本本身将不可重定位。换句话说，将这些入口点和脚本复制到环境外部的位置将无法正常工作，因为它们引用的路径是相对于环境本身的。
--seed将种子包（
pip、setuptools和wheel中的一个或多个）安装到虚拟环境中 [env: UV_VENV_SEED=]请注意，Python 3.12+ 环境中不包含
setuptools和wheel。