摘要：在管理项目的依赖项时，uv 通过简洁的工作流程使你的生活变得更加轻松。这种工作流程允许你锁定项目的依赖项，以便其他开发者可以精确地重现你的环境，并且在几乎没有设置工作的情况下为你的代码做出贡献。
在管理项目的依赖项时，uv 通过简洁的工作流程使你的生活变得更加轻松。这种工作流程允许你锁定项目的依赖项，以便其他开发者可以精确地重现你的环境，并且在几乎没有设置工作的情况下为你的代码做出贡献。
在接下来的部分中，仍然使用前面的 uv 示例项目，你将学习用于安装、更新和移除外部包和库的基本 uv 命令。你还将了解这些命令如何创建和更新相应的配置文件，以确保可重现性。
现在，回到 uv 示例项目中，打开项目根文件夹中的 main.py 文件，添加如下示例代码（替换原有的示例代码）：
import argparseimport sysimport requestsdef get_breeds_info: response = requests.get("https://api.thecatapi.com/v1/breeds") response.raise_for_status return response.jsondef find_breed_info(breed_name): json_response = get_breeds_info for breed in json_response: if breed["name"] == breed_name: return breed return Nonedef display_breed_proFile(breed): print(f"\n{breed['name']:-^30s}") print(f"Origin: {breed['origin']}") print(f"Temperament: {breed['temperament']}") print(f"Life Span: {breed['life_span']} years") print(f"Weight: {breed['weight']['imperial']} lbs") if breed.get("wikipedia_url"): print(f"\nLearn more: {breed['wikipedia_url']}")def parse_args: parser = argparse.ArgumentParser( description="Get information about cat breeds" ) parser.add_argument( "breed", help="Name of cat breed (e.g., 'Siamese')", ) return parser.parse_argsdef main: args = parse_args try: breed = find_breed_info(args.breed) if not breed: print("Breed not found. Try another breed name.") return 0 display_breed_profile(breed) except Exception as e: print(f"Error: {e}") return 1 return 0if __name__ == "__main__": sys.exit(main)将代码放置到位后，你可能会尝试使用类似以下命令运行应用程序：
uv run main.py PersianTraceback (most recent call last): File "/Users/xxx/Personal/uv-demo/rpcats/main.py", line 4, in import requestsModuleNotFoundError: No module named 'requests'应用程序会因 ModuleNotFoundError 异常而失败。为什么？因为你尚未在工作环境中安装所需的依赖项。
在 cat 应用程序示例中，你需要 Requests 库，这是一个用于在 Python 中发起 HTTP 请求的流行库。你使用这个库从cat API 获取猫的信息。
继续运行以下命令，让 uv 添加 requests：
uv add requests此命令允许你将 Requests 库添加到项目的依赖项中，并将其安装到项目的虚拟环境中。运行完成后，检查你的 pyproject.toml 文件内容：
[project]name = "rpcats"version = "0.1.0"description = "显示指定品种的猫的信息。"readme = "README.md"requires-python = ">=3.13"dependencies = [ "requests>=2.32.3",]注意，uv add 自动更新了你的依赖项列表，将 requests 添加到 pyproject.toml 文件中。在这种情况下，安装的版本应大于或等于 2.32.3。
在内部，uv add 还会用版本信息更新 uv.lock 文件，内容包括：
直接依赖项：你的项目直接依赖的包。例如，你的cat应用程序依赖于 requests。传递依赖项：支持你的项目直接依赖项的包。例如，Requests 库依赖于 urllib3，它会作为传递依赖项被安装。你无需担心 uv.lock 文件的内容，也不应手动编辑它。相反，让 uv 来管理它。然而，你必须将其纳入版本控制。
正如你所总结的，uv add 为你完成了依赖项管理工作。它安装了依赖项，如有必要会编辑 pyproject.toml 文件，并保持 uv.lock 文件的更新。这确保了其他开发者可以重现你的工作环境。
想不想再试一次你的猫应用程序？继续运行它：
uv run main.py PersianPersianOrigin: Iran (Persia)Temperament: Affectionate, loyal, Sedate, QuietLife Span: 14 - 15 yearsWeight: 9 - 14 lbsLearn more: https://en.wikipedia.org/wiki/Persian_(cat)现在，你的cat 应用程序可以正常工作了。它发起 API 请求，处理响应，并显示目标猫种的信息。
注意：如果你正在处理一个现有的项目，并且希望从 requirements.txt 文件迁移到使用 uv，那么你可以运行以下命令：
$ uv add -r requirements.txt此命令会将你在现有的 requirements.txt 文件中声明的依赖项导入到 uv 的基础设施中。
你还可以使用 uv 来更新和移除依赖项。例如，假设自你发布 rpcats 应用程序的最新版本以来已经过去了一段时间，你希望继续开发并添加新功能。然而，你发现 Requests 库有一个新版本。
在这种情况下，你可以使用以下命令来升级 requests：
$ uv add --upgrade requests此命令升级了 requests，并更新了 uv.lock 文件中的版本信息。这一操作使你可以使用该库的最新版本，并确保其他开发者也能做到这一点。
如果你在某个时候决定你的项目不再需要某个依赖项，那么你可以使用以下命令将其移除：
$ uv remove例如，如果你希望你的 rpcats 应用程序一次检查多只猫，你可能会使用像 aiohttp 这样的库，它能够发起 异步 HTTP 请求。在这种情况下，你可以移除 requests 并添加 aiohttp。
需要注意的是，uv remove 还会移除传递依赖项，并相应地更新 pyproject.toml 和 uv.lock 文件。
在大多数开发环境中，你会有一些不是运行代码所必需，但对于开发代码至关重要的依赖项。例如，测试库（如 pytest）、代码格式化工具（如 Ruff）和静态类型检查器（如 mypy）可能是这些开发依赖项。
你可以使用 uv 来管理这些类型的依赖项。这次，你将使用带有 --dev 标志的 uv add 命令。例如，假设你希望为cat 应用程序编写测试。为此，你希望使用 pytest。因为你的项目不需要这个库来运行，所以你可以将其安装为开发依赖项：
此命令将在项目的虚拟环境中安装 pytest，并将其作为开发依赖项添加到你的 pyproject.toml 和 uv.lock 文件中。
$ uv add --dev pytestuv add --dev pytestResolved 11 packages in 2.23sPrepared 4 packages in 1.40sInstalled 4 packages in 16ms+ iniconfig==2.1.0+ packaging==25.0+ pluggy==1.6.0+ pytest==8.3.5运行上述命令后，检查 pyproject.toml 文件的内容，你会看到以下内容：
[project]name = "rpcats"version = "0.1.0"description = "显示指定品种的猫的信息。"readme = "README.md"requires-python = ">=3.13"dependencies = [ "requests>=2.32.3",][dependency-groups]dev = [ "pytest>=8.3.5",]突出显示的行显示了 uv 如何自动更新文件，将 pytest 添加到你的开发依赖项列表中。你也可以查看 uv.lock 文件的内容，确认 pytest 是否也已添加。
现在你可以为你的项目编写测试了！
正如你已经了解到的，uv 使用 uv.lock 文件来锁定项目的依赖项。锁定（locking）是指在锁定文件中捕获项目的特定依赖项。这一过程使得在所有可能的配置中（包括 Python 版本和发行版、操作系统和架构）重现你的工作环境成为可能。
作为对应操作，同步（syncing）是将锁定文件中的所需包安装到项目的开发环境中的过程。
锁定和同步过程均由 uv 自动处理。例如，当你执行 uv run 时，项目会在调用命令之前被锁定和同步。这种行为确保了你的项目环境始终是最新的。
现在，假设你从 GitHub 仓库拉取了cat 应用程序，并希望尝试运行它。在这种情况下，你将只有源代码和 uv 配置文件。你没有用于运行应用程序的适当 Python 虚拟环境及其所需的依赖项。
为了重现这种情况，你可以删除项目根目录中的 .venv/ 文件夹。然后，让 uv 为你完成繁重的工作：
$ uv run main.py "Scottish Fold"Using CPython 3.13.2Creating virtual environment at: .venvInstalled 9 packages in 53ms--------Scottish Fold---------Origin: United KingdomTemperament: Affectionate, Intelligent, Loyal, Playful, Social, Sweet, LovingLife Span: 11 - 14 yearsWeight: 5 - 11 lbsLearn more: https://en.wikipedia.org/wiki/Scottish_Fold正如你所看到的，uv 在尝试运行应用程序之前，会在 .venv/ 目录下创建一个专用的虚拟环境，然后安装依赖项，最后运行应用程序。
为了确保 uv 正确地重现了环境，你可以运行以下命令：
$ uv pip listPackage Version ---------certifi 2025.4.26charset-normalizer 3.4.2idna 3.10iniconfig 2.1.0packaging 25.0pluggy 1.6.0pytest 8.3.5requests 2.32.3urllib3 2.4.0这是安装在项目虚拟环境中的包及其具体版本的列表。你可以将此列表与 uv.lock 文件的内容进行比较。包和版本会一致，这确保了原始开发环境的精确重现。
注意：在上面的例子中，你使用了 uv 的 pip 接口。在这种情况下，这是完全有效的，因为你并没有改变环境，而只是从环境中检索信息。
最后，你可以使用以下命令显式锁定和同步你的项目：
$ uv lock$ uv sync如果你在运行项目时遇到问题，并希望确保你正在使用每个依赖项的正确版本，这些命令会非常有用。
来源：软件架构