uv-python多版本管理

基础信息

官网地址https://docs.astral.sh/uv/concepts/cache/#cache-directory

全局配置源

 macOS and Linux:
/etc/uv/uv.toml (or $XDG_CONFIG_DIRS/uv/uv.toml)
Windows 
%%APPDATA%%\ProgramData\uv\uv.toml


index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
extra-index-url = [
    "https://mirrors.aliyun.com/pypi/simple/",
    "https://pypi.douban.com/simple/",
    "http://pypi.mirrors.ustc.edu.cn/simple/"
]

常用命令

# 安装多个版本的python
uv python install 3.10 3.11 3.12 
可以换国内华为源加快下载速度`python-install-mirror = "https://ghproxy.cn/https://github.com/indygreg/python-build-standalone/releases/download"`
参考全局的uv.toml配置文件

index-url = "https://mirrors.aliyun.com/pypi/simple/"

extra-index-url = [
"http://pypi.tuna.tsinghua.edu.cn/simple/",
"http://pypi.douban.com/simple/",
"http://pypi.mirrors.ustc.edu.cn/simple/"
]

concurrent-downloads = 6
python-install-mirror = "https://ghproxy.cn/https://github.com/indygreg/python-build-standalone/releases/download"

# 项目初始化  确定使用python版本 初始化环境会创建pyproject.toml元数据文件

# 创建一个特定python版本的虚拟环境
uv python pin 3.10  # 多版本情况下如果要创建不同版本的项目,如果不先pin特定版本,init命令会在`.python-version`创建默认的python版本
uv init --project <项目名>  -p 3.10 也可以在init命令后通过-p或者--python指定版本
uv venv -p 3.10
uv add requests 安装模块


# 同步项目依赖 会根据pyproject.toml自动安装依赖
uv sync

# 更新依赖
uv sync --upgrade

# 缓存
uv add requests 和 uv sync 都会：
从 archives/ 中查找是否已下载 requests-*.whl
比如windows的默认缓存路径为 `%LOCALAPPDATA%\uv\cache`
目录结构如下
%LOCALAPPDATA%\uv\cache\
└── uv\
    └── cache/
        ├── archives/           # 存放下载的 .whl 和 .tar.gz 文件
        │   ├── requests-2.31.0-py3-none-any.whl
        │   ├── torch-2.8.0-cp310-cp310-win_amd64.whl
        │   └── ...
        │
        ├── wheels/             # 构建后的 wheel（用于安装）
        │   ├── some_package-1.0.0-py3-none-any.whl
        │   └── ...
        │
        └── metadata/           # 包的 JSON 元数据（来自 PyPI API）
            ├── requests/
            ├── torch/
            └── ...

uv cache prune 可清理所有命令产生的缓存

修改 uv sync和uv add的依赖解析源
#uv.lock 文件里的解析源：这是 uv 执行完指令后，记录下来的 结果，告诉未来的安装步骤 “具体下载哪一个” 文件,解析的是依赖关系
uv lock --index-url https://mirrors.aliyun.com/pypi/simple
uv lock --extra-index-url http://pypi.tuna.tsinghua.edu.cn/simple/ --extra-index-url http://pypi.douban.com/simple/  --extra-index-url http://pypi.mirrors.ustc.edu.cn/simple/


# 更换源
# 项目模式 在项目文件内的pyproject.toml文件进行修改
有2种写法区别.
[[index]] → 用于 uv.toml 文件
支持所有 uv 命令（包括 uv pip, uv python, uv sync 等）
在同一目录下，优先级高于 pyproject.toml


[[tool.uv.index]] → 用于 pyproject.toml 文件
是为了在标准 pyproject.toml 中嵌入 uv 配置
兼容 Python 项目的通用结构
❌ 如果同目录有 uv.toml，则 完全被忽略

# 针对uv add模式
# 官网文档 https://docs.astral.sh/uv/reference/settings/#index
[[tool.uv.index]]
# 主源，我们这里设置为阿里云
index-url = "https://mirrors.aliyun.com/pypi/simple/"

# 额外的备用源
# 当主源找不到包时，uv 会依次在这些备用源里查找
extra-index-url = [
    "http://pypi.tuna.tsinghua.edu.cn/simple/",
    "http://pypi.douban.com/simple/",
    "http://pypi.mirrors.ustc.edu.cn/simple/"
]



# 针对uv pip install 模式
# 官方文档 https://docs.astral.sh/uv/concepts/configuration-files/#configuring-the-pip-interface
[tool.uv.pip]
# 主源，我们这里设置为阿里云
index-url = "https://mirrors.aliyun.com/pypi/simple/"

# 额外的备用源
# 当主源找不到包时，uv 会依次在这些备用源里查找
extra-index-url = [
    "http://pypi.tuna.tsinghua.edu.cn/simple/",
    "http://pypi.douban.com/simple/",
    "http://pypi.mirrors.ustc.edu.cn/simple/"
]


#用户模式 在当前用户下进行全局配置uv.toml文件,这里还区分是当前用户和全局用户.

index-url = "https://mirrors.aliyun.com/pypi/simple/"
extra-index-url = ["http://pypi.tuna.tsinghua.edu.cn/simple/","http://pypi.douban.com/simple/","http://pypi.mirrors.ustc.edu.cn/simple/"]


#用户级别
 macOS and Linux:
~/.config/uv/uv.toml (or $XDG_CONFIG_HOME/uv/uv.toml) 
 windows
 %APPDATA%\uv\uv.toml

#全局系统级别
 macOS and Linux:
/etc/uv/uv.toml (or $XDG_CONFIG_DIRS/uv/uv.toml)
Windows 
%%APPDATA%%\ProgramData\uv\uv.toml