python 现代化包管理工具uv安装和使用

环境：windows 11

uv是目前python世界性能和规范比较好的工具，其他的工具都测试过了，要么规范比较差，要么使用体验感觉不好，

python现代化的包管理工具

官网文档：https://docs.astral.sh/uv/getting-started/installation/

github：https://github.com/astral-sh/uv

一个极其快速的Python包和项目管理器，用Rust编写。

🚀 一个工具来替换 pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv
⚡️ 比 快 10-100 倍。pip
🗂️ 提供全面的项目管理，并配备通用锁文件。
❇️ 运行脚本，支持内联依赖元数据。
🐍 安装和管理Python版本。
🛠️ 运行并安装以 Python 包形式发布的工具。
🔩 包含一个兼容 Pip 的接口，以提升性能，并配有 熟悉的CLI。
🏢 支持可扩展项目的 Cargo 风格工作区。
💾 磁盘空间高效，并支持全局缓存以实现依赖重复删除。
⏬ 可通过 or or 安装，无需 Rust 或 Python。curlpip
🖥️ 支持macOS、Linux和Windows。

安装

使用我们的独立安装程序安装 uv：

# 在macOS和Linux上
curl -LsSf https://astral.sh/uv/install.sh | sh

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

或者，从PyPI获取：

# 使用pip
pip install uv

# 使用pipx
pipx install uv

如果通过独立安装程序进行安装，uv可以自行更新到最新版本

uv self update

在国内大概率是安装不了，可以使用 steam++，现在叫 Watt Toolkit（免费的） https://steampp.net/ 代理一下github

注意：首次在 PowerShell 中运行脚本时，可能会因为安全策略而被阻止。你需要先执行以下命令来允许当前会话运行脚本。
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
当系统提示时，输入 Y 并按回车。

代理之后，直接使用github的脚本
https://github.com/astral-sh/uv/releases/tag/0.9.17

通过shell脚本安装预构建的二进制文件

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/astral-sh/uv/releases/download/0.9.17/uv-installer.sh | sh


通过PowerShell脚本安装预构建的二进制文件

powershell -ExecutionPolicy Bypass -c "irm https://github.com/astral-sh/uv/releases/download/0.9.17/uv-installer.ps1 | iex"

如果有代理上述方案是可以的，但是没有的话，大概率都是无法使用的，以下是windows版本下的方案：

# 下载链接
https://github.com/astral-sh/uv/releases

# 通过shell脚本安装预编译的二进制文件
curl --proto '=https' --tlsv1.2 -LsSf https://releases.astral.sh/github/uv/releases/download/0.11.1/uv-installer.sh | sh

# 通过PowerShell脚本安装预构建的二进制文件
powershell -ExecutionPolicy Bypass -c "irm https://releases.astral.sh/github/uv/releases/download/0.11.1/uv-installer.ps1 | iex"

Download uv 0.11.1

下载版本 uv-x86_64-pc-windows-msvc.zip
https://github.com/astral-sh/uv/releases/download/0.11.1/uv-x86_64-pc-windows-msvc.zip

把 uv.exe uvw.exe uvx.exe 三个文件放到 C:\uv
在把  C:\uv  加入环境变量，这样在windows上就可以使用了

基础使用

初始化一个新项目：
uv init my_project --python 3.13
cd my_project

通过venv指定当前执行版本
uv venv --python 3.13                                 

cat .python-version  
3.13

创建名为 .venv 的虚拟环境（默认）会根据 项目文件自动生产，每个项目一份.venv
uv venv

激活环境（macOS/Linux）
source .venv/bin/activate

激活环境（Windows）这个 .venv 直接放 python的代码目录，每次需要运行的时候，直接运行一下
.venv\Scripts\activate


这会创建基本的项目结构和 pyproject.toml 文件。
安装项目的依赖：
uv sync

虚拟环境不同python版本的切换
使用以下命令创建一个名为 .venv 的虚拟环境，并指定使用 Python 3.13：
uv venv --python 3.13

uv venv py313 --python 3.13

建议对这个第一次使用的同学，建议在项目目录下面生产.venv 文件，这样每次开发一个项目的时候激活一下，虽然不是很方便
如果使用pycharm的时候，设置的 .venv 的文件夹正确的话，windows的终端会自动识别

注意：如果设置的python的 python interpreter，不正确，要重新设置

uv cache clean
清除缓存，删除所有条目或与特定包相关的条目

uv cache prune
从缓存中修剪所有无法访问的对象

uv cache dir
显示缓存目录

uv cache size
显示缓存大小

为当前项目固定 Python 3.11 先下载3.11， 在当前目录会生成一个 .python-version的文件
uv python pin 3.10                                    
Pinned `.python-version` to `3.10`

推出虚拟环境
deactivate

传统安装包（一般不推荐）：
安装最新版本
uv pip install requests

安装特定版本
uv pip install requests==2.31.0

删除requests：
uv remove requests

从 requirements.txt 安装
uv pip install -r requirements.txt

安装包到开发环境：
uv pip install --dev pytest

升级包：
uv pip upgrade requests

卸载包：
uv pip uninstall requests

另一种 包管理，强烈建议使用这种方式，不然 pyproject.toml 的 dependencies 不会自动更新
添加requests：
uv add requests

删除requests：
uv remove requests

添加镜像
pyproject.toml

[[tool.uv.index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
default = true

了解已安装的包及其版本
uv tree

在项目虚拟环境中运行脚本：
uv run python myscript.py

或启动Django服务器：
uv run python manage.py runserver

# 导出当前环境的依赖
uv pip freeze > requirements.txt

# 导出生产环境依赖（排除开发依赖）
uv pip freeze --production > requirements.txt

uv 支持 pyproject.toml 格式的项目管理，这是现代 Python 项目的标准配置文件。

pip临时使用
pip install -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple some-package
注意，simple 不能少。 pip 要求使用 https ，因此需要 https 而不是 http

设为默认
升级 pip 到最新的版本后进行配置：
python -m pip install --upgrade pip
pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

更新 UV
uv self update

查看版本
uv self version

警告信息：uv Failed to hardlink files; falling back to full copy. This may lead to degraded performance
建议把 uv的cache放到你的项目，比如你的项目代码在D盘，uv cache最好放在一直，不然做链接的会报警告信息
uv cache dir
通常你会看到它在 C: 盘。

在项目所在盘符创建 cache 目录
例如你的项目在 D:：
D:\uv-cache

永久设置环境变量 UV_CACHE_DIR
PowerShell（推荐）
setx UV_CACHE_DIR D:\uv-cache

说明：
永久生效（用户级）
重启终端后生效
不影响系统稳定性

打开新终端并验证
uv cache dir
确认输出路径已经变为 D:\uv-cache。

重新安装依赖
uv add google-genai

错误信息：ms-playwright\chromium-1208\chrome-win64\D3DCompiler_47.dll'] { errno: -4048
uv add playwright

安装 浏览器包
playwright install chromium

这个时候需要注意的是两个问题，
1，就是当前你使用shell的权限，一定要使用管理员权限
2，缺少ms c++的库
3，缺少DirectX的dll库

使用管理员权限在shell执行，这里可能因为网路问题下载很慢

1，修改 PLAYWRIGHT_CDN_MIRRORS  的js的配置文件，我尝试的不行
project_name\.venv\Lib\site-packages\playwright\driver\package\lib\server\registry\index.js

const PLAYWRIGHT_CDN_MIRRORS = [
  "https://cdn.playwright.dev/dbazure/download/playwright",
  // ESRP CDN
  "https://playwright.download.prss.microsoft.com/dbazure/download/playwright",
  // Directly hit ESRP CDN
  "https://cdn.playwright.dev"
  // Hit the Storage Bucket directly
];

2，设置环境变量 PLAYWRIGHT_CDN_MIRRORS ，也可以尝试

设置 python interpreter

帮助说明

PS C:\Users\Administrator> uv help
一个极快的 Python 包管理器。

用法：uv [选项] <命令>

命令：
  auth                       管理身份验证
  run                        运行命令或脚本
  init                       创建新项目
  add                        向项目添加依赖项
  remove                     从项目中移除依赖项
  version                    读取或更新项目版本
  sync                       更新项目的环境
  lock                       更新项目的锁定文件
  export                     将项目的锁定文件导出为其他格式
  tree                       显示项目的依赖树
  format                     格式化项目中的 Python 代码
  tool                       运行和安装由 Python 包提供的命令
  python                     管理 Python 版本和安装
  pip                        使用与 pip 兼容的接口管理 Python 包
  venv                       创建虚拟环境
  build                      将 Python 包构建为源码发行版和 wheel 包
  publish                    将发行版上传到索引
  cache                      管理 uv 的缓存
  self                       管理 uv 可执行文件本身
  generate-shell-completion  生成 shell 自动补全
  help                       显示命令的文档

缓存选项：
  -n, --no-cache               避免读写缓存，而是在操作期间使用临时目录
                               [环境变量：UV_NO_CACHE=]
      --cache-dir <缓存目录>    缓存目录的路径 [环境变量：UV_CACHE_DIR=]

Python 选项：
      --managed-python        要求使用由 uv 管理的 Python 版本 [环境变量：UV_MANAGED_PYTHON=]
      --no-managed-python     禁用由 uv 管理的 Python 版本 [环境变量：UV_NO_MANAGED_PYTHON=]
      --no-python-downloads   禁用 Python 的自动下载。 [环境变量：UV_PYTHON_DOWNLOADS=never]

全局选项：
  -q, --quiet...                                  使用安静输出
  -v, --verbose...                                使用详细输出
      --color <颜色选择>                          控制输出中颜色的使用 [可选值：auto, always, never]
      --native-tls                               是否从平台原生证书存储加载 TLS 证书 [环境变量：
                                                  UV_NATIVE_TLS=]
      --offline                                  禁用网络访问 [环境变量：UV_OFFLINE=]
      --allow-insecure-host <允许不安全的主机>     允许到主机的非安全连接 [环境变量：UV_INSECURE_HOST=]
      --no-progress                              隐藏所有进度输出 [环境变量：UV_NO_PROGRESS=]
      --directory <目录>                         在运行命令前切换到指定目录 [环境变量：UV_WORKING_DIR=]
      --project <项目>                           在指定目录中发现项目 [环境变量：UV_PROJECT=]
      --config-file <配置文件>                   要用于配置的 `uv.toml` 文件路径 [环境变量：UV_CONFIG_FILE=]
      --no-config                                避免发现配置文件 (`pyproject.toml`, `uv.toml`) [环境变量：UV_NO_CONFIG=]
  -h, --help                                     显示此命令的简要帮助信息
  -V, --version                                  显示 uv 版本

使用 `uv help <命令>` 获取特定命令的更多信息。

uv venv -h 帮助文档

创建虚拟环境 (Create a virtual environment)
用法: uv.exe venv [OPTIONS] [PATH]
参数 (Arguments)
[PATH]: 要创建的虚拟环境的路径。
选项 (Options)
基础选项
--no-project: 避免发现项目或工作区。
--seed: 将种子包（以下一个或多个：pip、setuptools 和 wheel）安装到虚拟环境中。
环境变量: UV_VENV_SEED=
-c, --clear: 删除目标路径下的任何现有文件或目录。
环境变量: UV_VENV_CLEAR=
--allow-existing: 保留目标路径下的任何现有文件或目录。
--prompt <PROMPT>: 为虚拟环境提供一个替代的提示前缀。
--system-site-packages: 允许虚拟环境访问系统的 site-packages 目录。
--relocatable: 使虚拟环境可重定位。
环境变量: UV_VENV_RELOCATABLE=
--index-strategy <INDEX_STRATEGY>: 解析多个索引 URL 时使用的策略。
环境变量: UV_INDEX_STRATEGY=
可选值: first-index, unsafe-first-match, unsafe-best-match
--keyring-provider <KEYRING_PROVIDER>: 尝试使用 keyring 对索引 URL 进行身份验证。
环境变量: UV_KEYRING_PROVIDER=
可选值: disabled, subprocess
--exclude-newer <EXCLUDE_NEWER>: 将候选包限制为在给定日期之前上传的包。
环境变量: UV_EXCLUDE_NEWER=
--exclude-newer-package <EXCLUDE_NEWER_PACKAGE>: 将特定包的候选包限制为在给定日期之前上传的包。
--link-mode <LINK_MODE>: 从全局缓存安装包时使用的方法。
环境变量: UV_LINK_MODE=
可选值: clone, copy, hardlink, symlink
Python 选项 (Python options)
-p, --python <PYTHON>: 用于虚拟环境的 Python 解释器。
环境变量: UV_PYTHON=
--managed-python: 要求使用 uv 管理的 Python 版本。
环境变量: UV_MANAGED_PYTHON=
--no-managed-python: 禁用使用 uv 管理的 Python 版本。
环境变量: UV_NO_MANAGED_PYTHON=
--no-python-downloads: 禁用自动下载 Python。
环境变量: "UV_PYTHON_DOWNLOADS=never"
索引选项 (Index options)
--index <INDEX>: 解析依赖项时使用的 URL，除了默认索引之外。
环境变量: UV_INDEX
--default-index <DEFAULT_INDEX>: 默认包索引的 URL（默认值：<https://pypi.org/simple>）。
环境变量: UV_DEFAULT_INDEX
-i, --index-url <INDEX_URL>: (已废弃：请改用 --default-index) Python 包索引的 URL（默认值：<https://pypi.org/simple>）。
环境变量: UV_INDEX_URL
--extra-index-url <EXTRA_INDEX_URL>: (已废弃：请改用 --index) 要使用的额外包索引 URL，除了 --index-url 之外。
环境变量: UV_EXTRA_INDEX_URL
-f, --find-links <FIND_LINKS>: 搜索候选发行版的位置，除了在注册表索引中找到的位置之外。
环境变量: UV_FIND_LINKS
--no-index: 忽略注册表索引（例如，PyPI），而是依赖于直接 URL 依赖项和通过 --find-links 提供的依赖项。
缓存选项 (Cache options)
--refresh: 刷新所有缓存数据。
-n, --no-cache: 避免从缓存读取或写入缓存，而是在操作期间使用临时目录。
环境变量: UV_NO_CACHE=
--refresh-package <REFRESH_PACKAGE>: 刷新特定包的缓存数据。
--cache-dir <CACHE_DIR>: 缓存目录的路径。
环境变量: UV_CACHE_DIR=
全局选项 (Global options)
-q, --quiet...: 使用安静输出。
-v, --verbose...: 使用详细输出。
--color <COLOR_CHOICE>: 控制输出中颜色的使用。
可选值: auto, always, never
--system-certs: 是否从平台的原生证书存储加载 TLS 证书。
环境变量: UV_SYSTEM_CERTS=
--offline: 禁用网络访问。
环境变量: UV_OFFLINE=
--allow-insecure-host <ALLOW_INSECURE_HOST>: 允许与主机建立不安全的连接。
环境变量: UV_INSECURE_HOST=
--no-progress: 隐藏所有进度输出。
环境变量: UV_NO_PROGRESS=
--directory <DIRECTORY>: 在运行命令之前切换到给定目录。
环境变量: UV_WORKING_DIR=
--project <PROJECT>: 在给定目录中发现一个项目。
环境变量: UV_PROJECT=
--config-file <CONFIG_FILE>: 要用于配置的 uv.toml 文件的路径。
环境变量: UV_CONFIG_FILE=
--no-config: 避免发现配置文件 (pyproject.toml, uv.toml)。
环境变量: UV_NO_CONFIG=
-h, --help: 显示此命令的简洁帮助。