uv-快速实践(2)

1.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"

uv help 查看是否安装成功

2. python版本管理

#指定镜像源（不指定默认公共源）
$env:UV_PYTHON_INSTALL_MIRROR="xxx" 

#指定pypi源（不指定默认公共源）
$env:UV_INDEX_URL="https://xxx/pypi/pypi-gliese-virtual/simple"

#安装指定版本python
uv python install 3.13.2

# 查看已安装和可安装的Python版本
uv python list

3. 创建项目

uv init myproject
cd myproject

自动生成：

• pyproject.toml：项目元信息（名称、版本、Python 版本、依赖等）
• uv.lock：锁定所有依赖及其子依赖（禁止手动编辑）
• .gitignore、.python-version、hello.py（示例代码）

4. 同步依赖（uv sync）

uv sync

• 自动查找并安装合适的 Python 版本
• 创建虚拟环境 .venv
• 生成 uv.lock 文件，确保依赖一致性
• 一键完成环境搭建

注： uv pip sync 与 uv sync 的区别：

uv pip sync专注于 Python 包依赖的同步。 严格按照 uv.lock（或兼容的 requirements.txt）文件，将当前虚拟环境的依赖与锁定文件保持完全一致。（安装锁定文件中所有依赖的精确版本、卸载锁定文件中没有的依赖、不会修改 uv.lock 本身）；

uv sync包含了虚拟环境创建、锁定文件生成、依赖安装的全流程。 uv 的项目级全量同步命令，一个 “一站式” 命令，帮你从 0 到 1 搭建好完整的开发环境，会一次性完成项目的完整初始化（如果没有虚拟环境，会自动创建、如果 uv.lock 不存在，会先根据 pyproject.toml 生成它、最后再调用 uv pip sync 来同步依赖）；

5. 运行项目

uv run hello.py

✅ 建议始终使用 uv run 运行代码，而非 python hello.py。（使用 uv run 运行代码会自动激活项目配置的虚拟环境并使用该环境中安装的 Python 版本和依赖包，确保运行环境与项目配置完全一致，避免因系统全局 Python 或其他环境导致的依赖版本不匹配问题。而直接使用 python hello.py 会使用系统默认的 Python 解释器，可能不是项目指定的版本，也可能缺少项目所需的依赖包，从而导致运行出错。此外，uv run 还能自动处理项目中定义的 Python 版本和依赖关系，使项目运行更加可靠和可复现。）

6. 管理依赖

• 添加依赖：

  uv add pandas
  

  自动递归安装所有依赖（如 numpy、pytz 等），速度极快。

• 删除依赖：

  uv remove pandas
  

  自动清理所有相关依赖，并更新 uv.lock。

7. 区分开发与生产依赖

uv add --group dev pandas      # 开发环境依赖
uv add --group production requests  # 生产环境依赖

• pyproject.toml 中会生成：

  [dependency-groups]
  dev = ["pandas>=2.2.3"]
  production = ["requests>=2.32.3"]
  

• 可分别同步：

  uv sync --group dev       # 只安装开发依赖
  uv sync --group production