Classmate Wang's blog

深浅模式

poetry ​

(传统稳健派)如果你加入的团队已经在使用 Poetry，或者需要构建复杂的 Python 包发布到 PyPI，用这个。

安装 ​

(推荐用 pipx):

bash
pipx install poetry

pipx 是一个专门用来安装和运行 Python 命令行工具（比如 Poetry）的工具。你需要先安装 pipx，才能用它来安装 Poetry。

  • pip install pipx pip 安装 pipx
  • python -m pipx ensurepath 将 pipx 添加到系统路径 这一步非常关键，它会确保你可以直接在命令行输入 pipx
  • 关闭并重新打开终端，使路径生效

初始化 ​

bash
mkdir my-project && cd my-project
poetry init

添加依赖 ​

bash
poetry add flask

⚠️ 注意：Poetry 解决依赖冲突（Resolving dependencies）时可能会卡很久，这是它的痛点，也是 uv 诞生的原因。

poetry的虚拟环境.venv不在项目根目录中,而是统一放在系统的缓存目录C:\Users...\AppData\Local\pypoetry\Cache\virtualenvs）。这样做是为了让项目目录保持干净。如果你习惯像 venv 或 uv 那样在项目根目录下看到 .venv 文件夹，你需要修改 Poetry 的配置。

  • 第一步：修改配置（开启项目内环境）poetry config virtualenvs.in-project true
  • 第二步：删除旧的“隐形”环境, 确保新环境生效
bash
# 查看当前环境在哪里
poetry env info --path
# 删除它（复制上面的路径，或者直接用 --all）：可能需要手动删除
poetry env remove --all
  • 第三步：重新安装 poetry install

如果安装失败 err info: If you want to use Poetry only for dependency management but not for packaging, you can disable package mode by setting package-mode = false in your pyproject.toml file.

在 pyproject.toml 添加

bash
[tool.poetry]
...
# 关键修改：package-mode 必须放在这里
package-mode = false # 告诉 Poetry：“这不是一个库，只管好依赖就行。”
...

进入虚拟环境 ​

Poetry 2.0（2025年1月发布）带来的重大更新。在 Poetry 2.0 中，为了给核心功能“瘦身”，官方把 shell 命令剥离出去了。

  1. 我想恢复 poetry shell 命令 ，只需要安装官方插件 poetry self add poetry-plugin-shell.
bash
poetry shell
# 现在你的终端前缀变了，可以直接运行 python main.py
  1. 使用原生 PowerShell 激活（更通用的做法 uv 也是这样做的）
  • 确保虚拟环境在项目目录下（可选但推荐）： 这能让你直接看到 .venv 文件夹，方便管理。
bash
  # 如果这是你第一次设置，可能需要运行 poetry env remove --all 然后 poetry install 重新生成环境
  poetry config virtualenvs.in-project true
  • 运行激活脚本
bash
  .\.venv\Scripts\Activate.ps1
  # 成功标志： 你的命令行前面会出现 (项目名-py3.x) 的提示符。

同步环境 ​

拿到别人的 pyproject.toml 和 poetry.lock

bash
poetry install  # 安装 pyproject.toml 中指定的所有依赖

poetry install 会自动创建虚拟环境（如果不存在），并根据 poetry.lock 安装所有依赖。

Poetry迁移uv ​

1. 导出当前依赖 (保留“遗产”) ​

  • 为了保证迁移后依赖版本不乱，我们需要先从 Poetry 导出纯文本的依赖列表。
bash
# 导出正式依赖
poetry export --without-hashes --format=requirements.txt > requirements.txt  # 导出依赖到 requirements.txt

# 导出开发依赖
poetry export --with dev --without-hashes --format=requirements.txt > requirements-dev.txt  # 导出开发依赖到 dev-requirements.txt

⚠️注意：如果 requirements-dev.txt 里包含重复的正式依赖也没关系，uv 会处理，或者你可以手动筛选一下只保留测试/Lint 工具

2. 清理旧门户 (备份与删除) ​

我们需要移除 Poetry 的痕迹，为 uv 腾出位置。

  • 备份：
    • 备份 pyproject.toml 和 poetry.lock 到安全的地方。
  • 删除：
    • 删除旧虚拟环境.venv
    • 删除 pyproject.toml 和 poetry.lock 文件。
    • （可选）删除虚拟环境目录（如果存在）。

3. 现在我们用 uv 创建一个新的、标准的 pyproject.toml。 ​

  • 初始化
bash
uv init  # 创建新的 pyproject.toml

这会在当前目录生成一个新的 pyproject.toml（符合 PEP 621 标准）和一个 .python-version 文件。

  • 设置 Python 版本
bash
uv init --python 3.12  # 创建新的 pyproject.toml 并指定 Python 版本为 3.12

4. 导入依赖 (数据迁移) ​

利用 uv 强大的导入功能，将刚才导出的 txt 文件读回来。

  • 正式依赖
bash
uv add -r requirements.txt  # 导入正式依赖
  • 开发依赖
bash
uv add -r requirements-dev.txt --dev  # 导入开发依赖

此时，uv 会自动生成 uv.lock 并创建 .venv 虚拟环境。

5. 手动迁移元数据 (最后修补) ​

  • 打开旧的 pyproject.toml.old 和新的 pyproject.toml，你需要手动搬运一些非依赖的信息，因为格式变了。