Mac 使用 uv 开发第一个 Python 项目

林发和大约 7 分钟

Mac 使用 uv 开发第一个 Python 项目

本文记录时间：2026-07-15。命令以 macOS 的 zsh 终端为主。

uv 是 Astral 开发的 Python 包和项目管理工具。它可以用来管理 Python 版本、创建项目、创建虚拟环境、安装依赖、生成锁文件、运行脚本和测试。对于日常 Python 项目开发来说，它可以替代很多常见工具的组合，例如 pip、venv、pip-tools、pipx、部分 pyenv 工作流等。

官方文档：

uv 安装文档：https://docs.astral.sh/uv/getting-started/installation/
uv 项目文档：https://docs.astral.sh/uv/guides/projects/
uv Python 版本管理：https://docs.astral.sh/uv/guides/install-python/

1. 安装 uv

方法一：官方安装脚本

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

安装完成后，重新打开一个终端窗口，或者执行：

source ~/.zshrc

检查是否安装成功：

uv --version

方法二：Homebrew 安装

如果已经安装了 Homebrew，也可以使用：

brew install uv

检查版本：

uv --version

2. 开启 zsh 命令补全

可选，但推荐配置。这样输入 uv 命令时可以使用 Tab 补全。

echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc
source ~/.zshrc

如果使用的是 ~/.zprofile 或其他 shell 配置文件，可以根据自己的终端配置调整。

3. 安装 Python

uv 可以自动下载和管理 Python。比如安装 Python 3.12：

uv python install 3.12

查看当前可用的 Python 版本：

uv python list

查看系统里能被 uv 找到的 Python：

uv python find

如果后续项目里指定了 Python 版本，而本机还没有对应版本，uv 通常会自动下载所需版本。

4. 创建第一个项目

先准备一个代码目录：

mkdir -p ~/Code
cd ~/Code

创建一个名为 hello-uv 的项目：

uv init hello-uv
cd hello-uv

创建后，目录大致如下：

hello-uv/
├── .git/
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

常见文件说明：

.python-version：记录当前项目使用的 Python 版本。
pyproject.toml：Python 项目的核心配置文件，记录项目名称、版本、依赖等信息。
main.py：默认生成的入口脚本。
.gitignore：Git 忽略文件配置。
README.md：项目说明。

5. 固定项目 Python 版本

进入项目目录后，固定使用 Python 3.12：

uv python pin 3.12

检查 .python-version：

cat .python-version

应该能看到类似：

3.12

以后在这个目录中运行 uv run ... 时，uv 会优先使用项目指定的 Python 版本。

6. 第一次运行项目

运行默认生成的 main.py：

uv run main.py

第一次运行时，uv 会自动做几件事：

根据项目配置创建 .venv 虚拟环境。
安装项目依赖。
生成或更新 uv.lock 锁文件。
使用项目虚拟环境运行脚本。

运行后目录中通常会多出：

.venv/
uv.lock

说明：

.venv/ 是本地虚拟环境，不需要提交到 Git。
uv.lock 是依赖锁文件，建议提交到 Git，方便不同电脑安装出一致的依赖版本。

7. 添加第一个依赖

添加一个适合演示的终端美化库 rich：

uv add rich

这个命令会：

修改 pyproject.toml，添加依赖声明。
修改 uv.lock，锁定精确版本。
同步当前虚拟环境。

查看项目依赖：

uv tree

8. 编写第一个程序

用 VS Code 打开项目：

code .

如果 code 命令不可用，可以使用：

open -a "Visual Studio Code" .

编辑 main.py：

from datetime import datetime

from rich.console import Console
from rich.panel import Panel


def build_message(name: str) -> str:
    return f"你好，{name}！欢迎使用 uv。"


def main() -> None:
    console = Console()
    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    message = f"{build_message('Mac')}\n当前时间：{now}"
    console.print(Panel.fit(message, title="hello-uv"))


if __name__ == "__main__":
    main()

运行：

uv run main.py

如果一切正常，终端中会看到一个由 rich 渲染的面板。

9. 添加测试

安装 pytest，并把它作为开发依赖：

uv add --dev pytest

创建测试目录：

mkdir tests
touch tests/test_main.py

编辑 tests/test_main.py：

from main import build_message


def test_build_message() -> None:
    assert build_message("Mac") == "你好，Mac！欢迎使用 uv。"

运行测试：

uv run pytest

也可以显示更详细的测试输出：

uv run pytest -v

10. 添加格式化和代码检查

安装 ruff：

uv add --dev ruff

运行代码检查：

uv run ruff check .

自动修复部分问题：

uv run ruff check . --fix

格式化代码：

uv run ruff format .

日常开发可以按这个顺序执行：

uv run ruff format .
uv run ruff check .
uv run pytest

11. 理解 pyproject.toml

执行 uv add rich 和 uv add --dev pytest ruff 后，pyproject.toml 里会出现类似内容：

[project]
name = "hello-uv"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "rich>=13.0.0",
]

[dependency-groups]
dev = [
    "pytest>=8.0.0",
    "ruff>=0.5.0",
]

实际版本号会根据执行命令时的最新版本变化。

重点理解：

dependencies：项目运行时需要的依赖。
dependency-groups.dev：开发时需要的依赖，例如测试、格式化、类型检查工具。
requires-python：项目要求的 Python 版本范围。

12. 提交到 Git

查看当前文件状态：

git status

建议提交这些文件：

.gitignore
.python-version
README.md
main.py
pyproject.toml
uv.lock
tests/test_main.py

不要提交：

.venv/

如果 .gitignore 正常，.venv/ 应该已经被忽略。

提交代码：

git add .
git commit -m "Create first uv Python project"

13. 常用 uv 命令速查

项目创建和运行

uv init hello-uv
cd hello-uv
uv run main.py
uv run python main.py

Python 版本

uv python install 3.12
uv python list
uv python find
uv python pin 3.12

依赖管理

uv add requests
uv add rich
uv add --dev pytest
uv add --dev ruff
uv remove requests
uv tree

环境同步

uv sync
uv sync --dev
uv lock

运行工具

uv run pytest
uv run ruff check .
uv run ruff format .
uv run python --version

升级依赖

升级全部依赖：

uv lock --upgrade
uv sync

升级某个依赖：

uv lock --upgrade-package rich
uv sync

14. 是否需要手动激活虚拟环境

一般不需要。

推荐使用：

uv run main.py
uv run pytest
uv run ruff check .

这样每次命令都会在项目虚拟环境中执行。

如果确实想手动激活虚拟环境，也可以：

source .venv/bin/activate
python main.py
deactivate

但在 uv 工作流中，更多时候直接使用 uv run ... 更清爽。

15. 换电脑后如何运行项目

别人拿到项目后，只需要安装 uv，然后执行：

cd hello-uv
uv sync
uv run main.py
uv run pytest

如果 .python-version 指定了某个 Python 版本，而本机没有，uv 可以自动下载所需 Python。

16. 常见问题

uv: command not found

说明终端还没有找到 uv 命令。可以尝试：

source ~/.zshrc

或者重新打开终端。

如果仍然不行，检查安装路径是否在 PATH 中：

echo $PATH

code 命令不可用

在 VS Code 中打开命令面板，搜索：

Shell Command: Install 'code' command in PATH

执行后重新打开终端，再使用：

code .

也可以直接用 macOS 命令打开：

open -a "Visual Studio Code" .

依赖安装后 import 仍然失败

先确认是在项目目录下运行：

pwd

再确认使用的是 uv run：

uv run python -c "import rich; print(rich.__version__)"

如果直接运行：

python main.py

可能用到的是系统 Python，而不是项目虚拟环境。

什么时候使用 uv sync

当你从 Git 拉取了别人的更新，或者切换分支后依赖有变化，可以执行：

uv sync

它会根据 pyproject.toml 和 uv.lock 同步本地虚拟环境。

17. 推荐的第一个项目结构

刚开始可以使用最简单结构：

hello-uv/
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
├── uv.lock
└── tests/
    └── test_main.py

等项目变复杂后，再改成包结构：

hello-uv/
├── src/
│   └── hello_uv/
│       ├── __init__.py
│       └── main.py
├── tests/
│   └── test_main.py
├── pyproject.toml
└── uv.lock

新手阶段先不要急着把结构做复杂。能运行、能测试、能提交、能在另一台机器复现，就是一个很好的起点。

18. 一套完整命令回顾

从零开始可以直接按下面执行：

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.zshrc
uv --version

uv python install 3.12

mkdir -p ~/Code
cd ~/Code
uv init hello-uv
cd hello-uv

uv python pin 3.12
uv run main.py

uv add rich
uv add --dev pytest ruff

mkdir tests
touch tests/test_main.py

uv run main.py
uv run ruff format .
uv run ruff check .
uv run pytest

git status
git add .
git commit -m "Create first uv Python project"

到这里，一个最小但完整的 Python 项目就建好了：有固定 Python 版本、有依赖管理、有虚拟环境、有锁文件、有测试、有格式化和代码检查。