一、官网
https://docs.astral.sh/uv/
- 一个用Rust编写且极其快速的Python包和项目管理器。
- 一站式提供： Python版本安装与切换 虚拟环境创建与隔离 依赖安装、锁定与更新 项目构建、打包与发布
- 本文提供两种使用uv的思想，仅供参考。 官方参考链接：概念 命令 设置 临时目录
二、 现代方式
替代 pip+pipx+virtualenv+pip-tools+poetry+pyenv+twine等 ,让环境搭建与项目管理更简单、更高效 依赖管理：支持 pyproject.toml/requirements.txt。 团队主要选型uv，主要使用 pyproject.toml+uv.lock、有兼容requirements.txt的需求
1.以uv为基础，独立安装
WinGet安装uv
winget install –id=astral-sh.uv -e
2.安装与配置python(UV支持下载和安装CPython、PyPy和Pyodide发行版。)
https://docs.astral.sh/uv/concepts/python-versions/ https://docs.astral.sh/uv/reference/cli/ https://docs.astral.sh/uv/reference/settings/
uv python 常用命令
//查看所有安装过的版本（默认配置下，可安装的版本会提示，当设置仅显示托管的，就只显示托管的安装<=>uv python list –managed-python）
uv python list
//显示可用的python版本
uv python list –only-downloads
//仅查看托管的
uv python list –managed-python
//仅查看系统安装的
uv python list –no-managed-python
//安装指定版本
uv python install 3.11.14
//卸载指定版本
uv python uninstall 3.12.12
如果你的系统已经安装了Python，UV会检测并使用它，无需配置。推荐使用 UV 托管的版本。 (1)可通过偏好配置仅使用UV托管的版本(为保证开发团队版本一致性约束) (2)默认会自动下载（当命令指定版本，版本不存在时）,可设为显式下载
// 修改 %APPDATA%\\uv\\uv.toml (修正不让自动下载、只使用uv托管)
python-downloads = "manual" 显式下载
python-preference = "only-managed" 仅使用托管的Python安装， 影响uv python list 显示（不会再显示系统的了）
python-install-mirror = "https://github.com/astral-sh/python-build-standalone/releases/download" 镜像源
修改python全局默认版本号（用户级）
//修改 %APPDATA%\\uv\\.python-version (或者uv python pin –global 3.11 )
3.11
支持以下 Python 版本请求格式（uv python list –only-downloads 查看后对照安装）：
<version>（例如 3 3.12 3.12.3)
<version-specifier>（例如，>=3.12,<3.13)
<version><short-variant>（例如，3.13t 3.12.0d)
<version>+<variant>（例如，， ，3.13+freethreaded 3.12.0+debug3.14+gil)
<implementation>（例如，或cpython cp)
<implementation>@<version>（例如，cpython@3.12)
<implementation><version>（例如，或cpython3.12 cp312)
<implementation><version-specifier>（例如，cpython>=3.12,<3.13)
<implementation>-<version>-<os>-<arch>-<libc>（例如，cpython-3.12.3-macos-aarch64-none)
python国内镜像源修改
南京大学: https://mirror.nju.edu.cn/github-release/astral-sh/python-build-standalone/
兰州大学: https://mirrors.lzu.edu.cn/github-release/astral-sh/python-build-standalone/
阿里云：https://registry.npmmirror.com/-/binary/python-build-standalone/
三、传统方式基础上,使用uv。
注意工具边界管理，仅使用现代包安装与依赖管理、打包、发布等。 依赖管理：支持 pyproject.toml/requirements.txt。 项目多且复杂、有高级打包需求、对pip工具链依赖太深。
1.已搭建(python+pip+pipx+virtualenv)开发环境,在此基础上扩展UV兼容
使用pipx安装uv
pipx install uv
2.与独立安装uv一样，可以禁止自动下载而显示的安装python,可以仅使用托管安装的python；
四、现代项目管理
1. 创建项目(uv init)
uv 支持两类基本模板：应用程序和库，默认创建应用程序。
uv init 创建应用，以目录名为名称
uv init myapp 创建应用，自定义应用名称
uv init –lib mylib 创建库（可以打包分发）
//不使用uv的模板，只生成项目依赖文件（pyproject.toml 和 uv.lock）而不生成应用代码文件
uv init –bare .
创建成功后，会自动根据全局python版本号，创建当前项目python版本文件.python-version、依赖文件pyproject.toml，应用程序或库目录结构与基础文件
可以使用以下命令，配置 uv的全局python版本号：
uv python pin –global 3.11
2. 修正当前项目python版本号(uv python pin )
项目开始或接到一份源码，我们会先确定使用的python版本
uv python pin 3.11 //确定当前项目版本号，如果没有.python-version则创建
3. 更新项目环境(uv sync)
如果未创建虚拟环境，会自动根据当前项目版本号创建项目环境。 同步确保所有项目依赖都已安装并与锁文件保持最新。
uv sync
4. 依赖包管理(uv add 、uv remove)
如果未创建虚拟环境，会自动根据当前项目版本号创建项目环境。
uv add <package_name> 添加依赖包,uv add requests==2.31.0 指定精确版本
uv remove <package_name> 移除依赖包
5. 更新项目的锁文件(uv lock)
如果项目锁文件（uv.lock）不存在，则会创建它。它主要用来确保依赖树的确定性、可重现性； 项目源码迁移时,库版本号做到确定性，与原环境一致性，顶层依赖可以在pyproject.toml看到，面向开人员的)。
uv lock
uv export > requirements.txt 导出安装依赖为需求文件,当未做uv lock时，自动创建
6. 查找可用的依赖包与配置依赖包的源
https://docs.astral.sh/uv/concepts/configuration-files/ https://docs.astral.sh/uv/reference/settings/
默认包源是PyPI，可去官网查包：https://pypi.org/ 可以修改默认源,配置优先级：命令>环境变量>项目级>用户全局级
6.1 在项目级别配置 (pyproject.toml)
[tool.uv]
index-url = "https://pypi.org/simple"
[tool.uv.pip]
extra-index-url = ["https://mirrors.aliyun.com/pypi/simple/"]
6.2 在用户全局级别配置 (uv.toml)
Linux/macOS: ~/.config/uv/uv.toml Windows: %APPDATA%\\uv\\uv.toml
index-url = "https://pypi.org/simple"
[pip]
extra-index-url = ["https://mirrors.aliyun.com/pypi/simple/"]
阿里云: https://mirrors.aliyun.com/pypi/simple/ 清华大学: https://pypi.tuna.tsinghua.edu.cn/simple/ 腾讯云: https://mirrors.cloud.tencent.com/pypi/simple/
7. uv缓存管理
uv cache clean 清除缓存，删除所有条目或与特定包相关的条目
uv cache prune 从缓存中修剪所有无法访问的对象
uv cache dir 显示缓存目录
uv cache size 显示缓存大小
8. 项目运行（运行命令或脚本）
当前目录或父目录中找到虚拟环境，则该命令将在该环境中执行。否则，命令将在发现的解释器环境中执行
uv run myapp.py //无需显式激活虚拟环境，使用uv命令的最佳实践（不用按传统pip的哪一套需要激活虚拟环境下管理运行项目）
五、库的打包与分发
https://docs.astral.sh/uv/reference/cli/#uv-build https://docs.astral.sh/uv/reference/cli/#uv-publish
六、兼容传统方式的能力(uv pip)
| 环境创建 | python -m venv .venv | uv venv |
| 激活环境 | .venv\\Scripts\\activate | 完全相同 |
| Python 3.11环境 | py 3.11 -m venv .venv | uv venv –python 3.11 |
| 安装单个包 | pip install requests | uv pip install requests |
| 从文件安装依赖 | pip install -r requirements.txt | uv pip install -r requirements.txt |
| 可编辑安装项目 pyproject.toml 安装 | pip install -e . | uv pip install -e . |
| 列出已安装包 | pip list | uv pip list |
| 导出依赖到文件 | pip freeze > requirements.txt | uv pip freeze > requirements.txt |
| 运行脚本（自动探测环境） | py main.py | uv run python main.py |
| 运行模块 | python -m mymodule | uv run python -m mymodule |
| 卸载包 | pip uninstall package | uv pip uninstall package |
七、uv-tools(替代如pipx等的命令行工具)
| uv tool run <package_command> | 运行一个Python包提供的命令。此命令会自动处理环境并安装依赖，然后运行指定命令。 | uv tool run ruff check |
| uv tool install <package> | 安装一个Python包及其提供的命令工具。安装后，该命令可以在系统的任意目录下使用。 | uv tool install build |
| uv tool upgrade <package> | 升级一个已经安装的Python工具包到最新版本。 | uv tool upgrade hatch |
| uv tool list | 列出所有通过uv tool install安装的Python工具包。 | uv tool list |
| uv tool uninstall <package> | 卸载一个之前安装的Python工具包。 | uv tool uninstall twine |
| uv tool update-shell | 确保系统环境变量PATH包含uv的工具目录路径。通常只需要在首次安装完一个新工具后运行一次。 | uv tool update-shell |
| uv tool dir | 显示uv存放已安装工具脚本的目录路径。 | uv tool dir |
