使用 UV 创建并运行 Python 项目（完整步骤）

在开始之前，请先确认 UV 已正常工作：

powershell

复制代码

uv --version
# 应该输出类似：uv 0.11.13 (x86_64-pc-windows-msvc)

一、创建新项目

1. 初始化项目

打开 PowerShell，进入你想存放项目的目录，然后运行：

powershell

复制代码

# 创建一个名为 my_first_uv_project 的新项目
uv init my_first_uv_project

# 进入项目目录
cd my_first_uv_project

UV 会自动完成以下操作：

创建项目目录结构
自动创建并激活虚拟环境（在 .venv 文件夹中）
生成 pyproject.toml 项目配置文件
生成 uv.lock 依赖锁定文件
创建一个简单的 main.py 示例文件

2. 查看项目结构

创建完成后，你的项目目录应该是这样的：

复制代码

my_first_uv_project/
├── .venv/              # 自动创建的虚拟环境
├── .gitignore          # Git 忽略文件
├── pyproject.toml      # 项目配置和依赖管理
├── uv.lock             # 依赖版本锁定文件
└── main.py             # 主程序入口

二、了解项目配置文件

pyproject.toml

这是现代 Python 项目的标准配置文件，UV 会自动生成一个基础版本：

复制代码

[project]
name = "my_first_uv_project"
version = "0.1.0"
description = ""
authors = [
  { name = "Your Name", email = "you@example.com" },
]
dependencies = []  # 项目依赖会在这里列出

[tool.uv]
# UV 特定配置

三、添加依赖

1. 添加生产依赖

powershell

复制代码

# 添加 requests 库
uv add requests

# 添加指定版本的库
uv add "fastapi>=0.110.0"

# 添加多个库
uv add numpy pandas matplotlib

2. 添加开发依赖

powershell

复制代码

# 添加 pytest 作为开发依赖
uv add pytest --dev

# 添加 black 代码格式化工具
uv add black --dev

添加依赖后，UV 会自动更新 pyproject.toml 和 uv.lock 文件。

四、编写代码

打开 main.py 文件，UV 已经为你生成了一个简单的示例：

复制代码

def main():
    print("Hello from my-first-uv-project!")

if __name__ == "__main__":
    main()

我们来修改一下，使用刚才安装的 requests 库：

复制代码

import requests

def main():
    print("正在获取 GitHub API 数据...")
    response = requests.get("https://api.github.com/users/octocat")
    
    if response.status_code == 200:
        data = response.json()
        print(f"用户名: {data['login']}")
        print(f"公开仓库数: {data['public_repos']}")
        print(f"粉丝数: {data['followers']}")
    else:
        print(f"请求失败，状态码: {response.status_code}")

if __name__ == "__main__":
    main()

五、运行项目

方法 1：使用 uv run（推荐）

这是 UV 推荐的运行方式，它会自动在虚拟环境中执行命令：

powershell

复制代码

# 运行 main.py
uv run python main.py

输出示例：

plaintext

复制代码

正在获取 GitHub API 数据...
用户名: octocat
公开仓库数: 8
粉丝数: 12345

方法 2：先激活虚拟环境再运行

如果你习惯传统的虚拟环境激活方式：

powershell

复制代码

# Windows PowerShell
.venv\Scripts\Activate.ps1

# 激活后，直接运行 python 命令
python main.py

# 退出虚拟环境
deactivate

六、进阶操作

1. 运行项目脚本

你可以在 pyproject.toml 中定义项目脚本，然后直接运行：

复制代码

[project.scripts]
hello = "my_first_uv_project.main:main"

然后运行：

powershell

复制代码

uv run hello

2. 运行测试

如果你安装了 pytest，可以直接运行：

powershell

复制代码

uv run pytest

3. 同步依赖

当你从 Git 拉取项目后，或者修改了 pyproject.toml 文件，可以运行：

powershell

复制代码

uv sync

这会根据 uv.lock 文件安装所有依赖，确保所有人使用相同的版本。

4. 更新依赖

powershell

复制代码

# 更新所有依赖到最新版本
uv lock --upgrade

# 更新特定依赖
uv lock --upgrade-package requests

七、常见问题

问题 1：运行时提示 "ModuleNotFoundError"

原因：依赖没有安装到虚拟环境中。

解决方案：

powershell

复制代码

# 同步所有依赖
uv sync

问题 2：虚拟环境没有自动创建

解决方案：

powershell

复制代码

# 手动创建虚拟环境
uv venv

问题 3：想使用特定版本的 Python

解决方案：

powershell

复制代码

# 先安装 Python 3.12
uv python install 3.12

# 使用 Python 3.12 创建项目
uv init --python 3.12 my_python_312_project

🔍 为什么没有自动创建.venv？

从 UV 0.11 版本开始，默认行为有所变化：

如果系统中已经有一个激活的虚拟环境（比如你的 Conda base 环境），UV 会优先使用它
全局配置中可能默认禁用了自动创建虚拟环境
这是 UV 的设计选择，不是 bug

✅ 解决方案：手动创建虚拟环境（推荐）

在你的项目根目录（包含pyproject.toml的文件夹）打开 PowerShell，运行：

powershell

复制代码

# 创建虚拟环境（会自动使用你配置的Python版本）
uv venv

运行成功后 ，你会看到项目中出现了.venv文件夹，同时 UV 会输出类似信息：

plaintext

复制代码

Creating virtual environment at: .venv
Using Python 3.12.3 from C:\Users\HP\.local\share\uv\python-3.12.3-x86_64-windows-msvc\python.exe

✅ 0.11.13 版本的正确配置方法

方法一：创建项目时强制创建虚拟环境（最简单）

在创建项目时直接加上 --venv 参数，UV 就会自动创建 .venv 文件夹：

powershell

复制代码

# 创建项目并自动创建虚拟环境
uv init --venv my_new_project