开始前准备

Python 与 uv:
建立独立项目环境

理解解释器、包和虚拟环境的关系,并把依赖留在项目自己的 .venv 中。

预计阅读 12 分钟公开免费核验于 2026.08.19
内容目录 当前:第 12
开始前准备6
Agent 基础5
工具安装与配置6
模型与接口5
进阶专题5
本文目录 3 个部分

大家好,我是云途。Python 项目最容易出现的情况,是这个项目能运行,换一台电脑却缺包;或者为了修一个项目,把另一个项目弄坏了。

解决方法不是记更多安装命令,而是让每个项目使用自己的虚拟环境和依赖说明。

解释器、包和虚拟环境是什么关系

系统提供运行时,项目环境隔离依赖,项目代码只依赖自己的环境。你的命令npm / npxnpm管理项目依赖npx执行包命令Node.js实际运行
系统提供运行时,项目环境隔离依赖,项目代码只依赖自己的环境。

Python 是运行代码的解释器;包是项目要用的第三方能力;.venv 是项目自己的隔离环境。uv 可以帮助创建环境、安装依赖并锁定版本。

建立第一个独立环境

在项目根目录执行SHELL
uv init
uv venv
uv add requests
uv run python --version
命令和参数可能随 uv 版本变化,实际操作前以官方文档为准。

项目应保留 pyproject.toml 与锁文件,但通常不要把 .venv 提交到 Git,也不要把它复制给别人。

环境混乱后怎样恢复

  1. 先确认当前目录和 pyproject.toml。
  2. 确认命令使用的是项目内环境,不是系统 Python。
  3. 依赖说明完整时,可以删除并重建 .venv;不要先修改系统 Python。
  4. 重新运行项目的测试或最小启动命令。
完成检查

Python 依赖已经留在项目内部

  • 项目存在 pyproject.toml。
  • 项目使用自己的 .venv。
  • 依赖由 uv 记录和锁定。
  • 没有把全局 Python 当作项目依赖。

官方依据与延伸阅读

uv 官方文档Python venv