如何使用uv创建并管理一个新的空白的python项目？

一、安装 uv

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

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或使用 pip
pip install uv

二、本地项目使用 uv 进行管理

2.1 创建新项目

# 创建项目目录
mkdir myproject
cd myproject

# 初始化项目（创建虚拟环境、pyproject.toml等）
uv init

或者使用一步到位的命令：

uv init myproject --python 3.11  # 指定Python版本和生成项目名称`myproject`
# 如果想要将当前目录作为项目，那么请使用：
uv init --python 3.12
cd myproject

2.2 项目结构

初始化后会生成：

myproject/
├── pyproject.toml    # 项目配置和依赖
├── README.md         # 项目说明
├── .gitignore        # Git忽略文件
└── src/
    └── myproject/    # 包源代码
        └── __init__.py

2. 3 管理依赖

# 添加依赖
uv add requests pandas numpy

# 添加开发依赖
uv add --dev pytest black mypy

# 从requirements.txt安装
uv pip compile requirements.txt -o pyproject.toml

# 安装所有依赖
uv sync

2.4 运行和管理

# 运行Python脚本
uv run python script.py

# 启动虚拟环境shell
uv shell

# 运行测试
uv run pytest

# 查看依赖树
uv tree

2.5 常用工作流示例

2.5.1 示例 pyproject.toml：

[project]
name = "myproject"
version = "0.1.0"
description = "My awesome project"
dependencies = [
    "requests>=2.28.0",
    "pandas>=2.0.0",
]

[project.optional-dependencies]
dev = ["pytest>=7.0.0", "black>=23.0.0"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

2.5.2 常用命令总结：

# 创建项目
uv init <project-name>

# 添加/移除依赖
uv add <package>
uv remove <package>

# 更新所有依赖
uv sync --upgrade

# 冻结依赖版本
uv lock

# 清理缓存
uv cache clean

三、 与现有项目集成

# 在现有项目中初始化uv
cd existing-project
uv init --force  # 保留现有pyproject.toml

# 从现有环境迁移
uv pip freeze > requirements.txt
uv add -r requirements.txt

uv 的优势在于速度快、集成好，同时支持依赖管理和虚拟环境管理。使用 uv 后，通常不再需要单独安装 pip、virtualenv、pip-tools 等工具。

四、当你拿到一个使用 uv 管理的项目

只需要三步就能够快速配置：1. 创建虚拟环境 2. 激活虚拟环境 3. 同步项目的依赖

4.1 先安装 uv（如果还没装）

# Windows（PowerShell）
irm https://astral.sh/uv/install.ps1 | iex

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

4.2 进入项目根目录

cd 你的项目文件夹

4.3 创建并激活虚拟环境（uv 风格）

# 创建虚拟环境（自动用项目 Python 版本）
uv venv
# 你可以指定本地 python 路径
uv venv --python "your python path."
# 激活
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

4.4 安装所有依赖（最关键）

uv sync

这会根据：

• pyproject.toml
• uv.lock

精确安装和原项目一模一样的依赖版本。

4.5. 运行项目

按项目原本的启动方式运行即可，例如：

uv run main.py
uv run fastapi dev main.py

---

最常用的 uv 命令（记这 5 个就够）

• uv add 包名：安装包
• uv remove 包名：卸载包
• uv sync：同步依赖
• uv run 命令：在虚拟环境里运行
• uv pip list：看已安装包