1. 安装

Introduction | Documentation | Poetry - Python dependency management and packaging made easy (python-poetry.org)

一打开就是一个大大的红色警告，敢情外国人也喜欢丑话说在前头。这个警告意思是说： Poetry 应该安装在一个独立的虚拟环境中，避免安装在项目的虚拟环境中。不然Poetry 容易被意外升级或者卸载。

基于这个警告，官方提供了3种靠谱的安装方式：

1.1 使用 pipx 安装

pipx 是一个专门用来安装和管理python工具的工具，读起来有点拗口，但不妨碍我不用他。官方文档都说了，如果安装了 pipx 可以使用这行命令快速完成。但我没有 pipx，所以我不用这个方式安装。

pipx install poetry

1.2 使用Shell命令安装

Linux Shell 用个命令

curl -sSL https://install.python-poetry.org | python3 -

Windows PowerShell 用这个命令

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

dddd 这两个命令都是去这个地址拉了一个python 脚本过来运行：install.python-poetry.org

我看看代码是怎么个事？算了看不懂，直接执行命令吧。执行完成之后需要把Poetry的可执行文件路径配置到PATH环境变量

默认的安装路径：

• $HOME/.local/bin on Unix.
• %APPDATA%\Python\Scripts on Windows.
• $POETRY_HOME/bin if $POETRY_HOME is set.

配置完成之后验证一下成功没有（如果你还没成功我建议你安装pipx去，那个适合你）

PS C:\Users\Administrator> poetry --version
Poetry (version 1.8.3)
PS C:\Users\Administrator>

1.3 使用 pip 手动安装

还记得最开始那个红色的警告吗？Poetry 应该安装在一个独立的虚拟环境中，避免安装在项目的虚拟环境中。那么手动安装的步骤就出来了：

# 第一步，创建一个虚拟环境
python3 -m venv $VENV_PATH
$VENV_PATH/bin/pip install -U pip setuptools

# 第二步，在虚拟环境中安装poetry
$VENV_PATH/bin/pip install poetry

同理修改 PATH 环境变量之后，验证是否成功。

2. 使用

Basic usage | Documentation | Poetry - Python dependency management and packaging made easy (python-poetry.org)

2.1 初始化项目

创建项目

# 创建项目
PS D:\workspace> poetry new poetry-demo
Created package poetry_demo in poetry-demo

# 目录结构
poetry-demo
├── pyproject.toml
├── README.md
├── poetry_demo
│   └── __init__.py
└── tests
    └── __init__.py

虚拟环境创建/启动/关闭

# 创建虚拟环境
PS D:\workspace\poetry-demo> poetry env use python
Creating virtualenv poetry-demo in D:\workspace\poetry-demo\.venv
Using virtualenv: D:\workspace\poetry-demo\.venv
PS D:\workspace\poetry-demo>

# 启动虚拟环境
PS D:\workspace\poetry-demo> poetry shell
Spawning shell within D:\workspace\poetry-demo\.venv
Windows PowerShell
Copyright (C) Microsoft Corporation. All rights reserved.

Install the latest PowerShell for new features and improvements! https://aka.ms/PSWindows
(poetry-demo-py3.12) PS D:\workspace\poetry-demo>


# 退出虚拟环境
(poetry-demo-py3.12) PS D:\workspace\poetry-demo> exit
PS D:\workspace\poetry-demo>

2.2 Poetry 基本命令

添加依赖模块

(poetry-demo-py3.12) PS D:\workspace\poetry-demo> poetry add fastapi 
Using version ^0.112.0 for fastapi

Updating dependencies
Resolving dependencies... (3.6s)

Package operations: 9 installs, 0 updates, 0 removals

  - Installing idna (3.7)
  - Installing sniffio (1.3.1)
  - Installing typing-extensions (4.12.2)
  - Installing annotated-types (0.7.0)
  - Installing anyio (4.4.0)
  - Installing pydantic-core (2.20.1)
  - Installing pydantic (2.8.2)
  - Installing starlette (0.37.2)
  - Installing fastapi (0.112.0)

Writing lock file
(poetry-demo-py3.12) PS D:\workspace\poetry-demo> 

添加完成之后，pyproject.toml 会自动添加 fastapi 的依赖记录，同时 poetry.lock也会更新，虚拟环境也会把库装载进去

[tool.poetry.dependencies]
python = "^3.12"
fastapi = "^0.112.0"

手动修改依赖

如果需要修改的东西比较多，需要手动修改 pyproject.toml，那就需要先同步poetry.lock 再刷新虚拟环境。

# 更新lock文件内容
poetry lock
Updating dependencies
Resolving dependencies... (7.5s)

Writing lock file

# 根据 lock 文件刷新虚拟环境依赖库
(poetry-demo-py3.12) PS D:\workspace\poetry-demo> poetry install
Installing dependencies from lock file

Package operations: 26 installs, 1 update, 0 removals

  - Installing mdurl (0.1.2)
  - Installing colorama (0.4.6)
  - Installing markdown-it-py (3.0.0)
  - Installing pygments (2.18.0)
  - Installing certifi (2024.7.4)
  - Installing click (8.1.7)
  - Installing h11 (0.14.0)
  - Installing httptools (0.6.1)
  - Installing python-dotenv (1.0.1)
  - Installing pyyaml (6.0.2)
  - Installing rich (13.7.1)
  - Installing shellingham (1.5.4)
  - Installing watchfiles (0.22.0)
  - Installing websockets (12.0)
  - Installing dnspython (2.6.1)
  - Installing httpcore (1.0.5)
  - Installing markupsafe (2.1.5)
  - Installing typer (0.12.3)
  - Installing uvicorn (0.30.5)
  - Installing email-validator (2.2.0)
  - Installing fastapi-cli (0.0.5): Installing...
  - Installing fastapi-cli (0.0.5)
  - Installing httpx (0.27.0)
  - Installing jinja2 (3.1.4)
  - Installing orjson (3.10.6)
  - Installing python-multipart (0.0.9)
  - Installing ujson (5.10.0)
  - Downgrading fastapi (0.112.0 -> 0.111.0)

Installing the current project: poetry-demo (0.1.0)
(poetry-demo-py3.12) PS D:\workspace\poetry-demo> 

删除依赖模块

和 pip 不同，poetry 不仅删除fastapi 的包，还会协调将依赖一并删除。

(poetry-demo-py3.12) PS D:\workspace\poetry-demo> poetry remove fastapi     
Updating dependencies
Resolving dependencies... (0.1s)

Package operations: 0 installs, 0 updates, 35 removals
  - Removing fastapi (0.111.0)
  - Removing fastapi-cli (0.0.5)
  - Removing h11 (0.14.0)
  - Removing httpcore (1.0.5)
  - Removing httptools (0.6.1)
  - Removing httpx (0.27.0)
  - Removing idna (3.7)
  - Removing jinja2 (3.1.4)
  - Removing markdown-it-py (3.0.0)
  - Removing markupsafe (2.1.5)
  - Removing mdurl (0.1.2)
  - Removing orjson (3.10.6)
  - Removing pydantic (2.8.2)
  - Removing pydantic-core (2.20.1)
  - Removing pygments (2.18.0)
  - Removing python-dotenv (1.0.1)
  - Removing python-multipart (0.0.9)
  - Removing pyyaml (6.0.2)
  - Removing rich (13.7.1)
  - Removing shellingham (1.5.4)
  - Removing sniffio (1.3.1)
  - Removing starlette (0.37.2)
  - Removing typer (0.12.3)
  - Removing typing-extensions (4.12.2)
  - Removing ujson (5.10.0)
  - Removing uvicorn (0.30.5)
  - Removing watchfiles (0.22.0)
  - Removing websockets (12.0)

Writing lock file
(poetry-demo-py3.12) PS D:\workspace\poetry-demo>

多Group依赖

我按照一个 pytest 依赖，这个测试框架只在开发的时候使用，上线的时候不必装载。这个时候就可以使用 group。将 pytest 安装到 dev 这个 group 下面。

(poetry-demo-py3.12) PS D:\workspace\poetry-demo> poetry add pytest --group dev
Using version ^8.3.2 for pytest

Updating dependencies
Resolving dependencies... (1.4s)

Package operations: 5 installs, 0 updates, 0 removals

  - Installing colorama (0.4.6)
  - Installing iniconfig (2.0.0)
  - Installing packaging (24.1)
  - Installing pluggy (1.5.0)
  - Installing pytest (8.3.2)

Writing lock file
(poetry-demo-py3.12) PS D:\workspace\poetry-demo>

[tool.poetry]
name = "poetry-demo"
version = "0.1.0"
description = ""
authors = ["hongweihao <xxxxxxxxx>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.12"


[tool.poetry.group.dev.dependencies]
pytest = "^8.3.2"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

导出为 requirements.txt

既然有了poetry 为什么还要 requirements.txt ？在部署环境中，可能不会专门提供 poetry。有了 requirements.txt 就可以抛弃 poetry，python + pip直接轻量级部署了

(poetry-demo-py3.12) PS D:\workspace\poetry-demo> poetry export --format requirements.txt --output requirements.txt --without-hashes

certifi==2024.7.4 ; python_version >= "3.12" and python_version < "4.0"
charset-normalizer==3.3.2 ; python_version >= "3.12" and python_version < "4.0"
idna==3.7 ; python_version >= "3.12" and python_version < "4.0"
requests==2.32.3 ; python_version >= "3.12" and python_version < "4.0"
urllib3==2.2.2 ; python_version >= "3.12" and python_version < "4.0"