uv 管理 Python 项目

下面是一个详细的使用说明，介绍如何使用 uv 管理 Python 项目，包括安装、初始化项目、管理依赖与虚拟环境等方面：

---

1. 安装 uv

uv 是由 Astral 推出的基于 Rust 编写的 Python 包和项目管理工具，号称“Python 的 Cargo”。你可以通过多种方式安装 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"
  

• 通过 pip 安装：

  pip install uv
  

安装后，可使用 uv help 检查是否安装成功。

---

2. 初始化项目

使用 uv 初始化项目非常简单。只需创建一个空文件夹，然后运行：

uv init myproject

这会在项目目录中生成以下几个文件：

• pyproject.toml：记录项目名称、版本、描述、所需 Python 版本以及依赖列表。
• .python-version：记录当前使用的 Python 版本。
• README.md 和 .gitignore 等文件。

例如，创建成功后的目录结构可能如下：

myproject/
  ├── .gitignore
  ├── .python-version
  ├── hello.py
  ├── pyproject.toml
  └── README.md

---

3. 同步环境与虚拟环境管理

同步依赖

首次进入项目后，运行以下命令可自动：

• 检测或下载合适的 Python 版本；
• 创建项目专用的虚拟环境（通常位于 .venv 目录下）；
• 根据 pyproject.toml 和现有依赖生成或更新 uv.lock 锁定文件；
• 同步依赖到虚拟环境中。

uv sync

运行后，若项目没有额外依赖，uv.lock 文件中只会记录最基本的信息。

创建和管理虚拟环境

如果需要手动管理虚拟环境，你可以使用：

• 创建虚拟环境：

  uv venv myenv
  

  若需要指定 Python 版本：

  uv venv --python /path/to/python myenv
  

• 激活虚拟环境：
  Linux/macOS 下：

  source myenv/bin/activate
  

  Windows 下：

  myenv\Scripts\activate
  

---

4. 管理依赖

uv 提供了类似于 npm 或 Cargo 的依赖管理命令，可以非常便捷地添加、删除或更新依赖包。

添加依赖

例如，添加 pandas 依赖：

uv add pandas

这时，uv 会自动解决 pandas 及其依赖，并更新 pyproject.toml（记录依赖）和 uv.lock（记录所有详细依赖版本信息）。

删除依赖

删除依赖也同样简单：

uv remove pandas

此命令会自动卸载 pandas 及其不再需要的依赖，同时更新锁定文件。

分组管理依赖

你还可以为开发环境和生产环境分别添加依赖，例如：

• 添加开发环境依赖：

  uv add --group dev pandas
  

• 添加生产环境依赖：

  uv add --group production requests
  

这些分组信息会记录在 pyproject.toml 的 [dependency-groups] 部分。

---

5. 运行项目

与传统直接调用 python hello.py 不同，uv 建议你使用统一的命令来运行项目代码。你可以使用：

uv run hello.py

该命令会自动在项目的虚拟环境中执行代码，确保所有依赖都已正确安装。

---

6. 其它 uv 命令

• uv pip：提供与 pip 兼容的接口管理包，例如安装、卸载、列出包等。
• uv lock：根据 pyproject.toml 更新或生成 uv.lock 文件，记录所有包的精确版本。
• uv tree：以树状结构显示项目的依赖关系，帮助你快速了解依赖层次结构。
• uv python find：查找已安装的 Python 版本。
• uv python list：列出可供安装的 Python 版本以及系统中已安装的版本。
• uv python install <version>：将 <version> 替换为您希望安装的多个 Python 版本号，例如 3.10 3.11 3.12 pypy@3.10。
• uv python pin <version>：固定当前目录下使用的python版本。
• uv run -p <version> python：进入指定python版本的解释器交互环境。

这些命令使得整个项目管理体验更为统一和高效。

7.总结

• 当前目录下默认用的python版本是uv python find对应版本.
• 当前目录下指定版本用uv python pin <version>会在当前目录下生成一个.python-version文件。
• 指定的Python版本运行指令: uv init/add/remove/run/pip -p <version>。