Python包管理工具poetry介绍

概述

poetry是一个Python包管理工具，他可以替代pip和virtualenv，提供了更好的依赖管理和包发布功能。

与其他包管理工具的对比

安装

linux包管理器

以Ubuntu 24.04为例：只需要使用apt安装即可

sudo apt-get install python3-poetry

上边命令不能执行的，也可以采用官网的其他方式，详见https://python-poetry.org/docs/#installation

脚本安装

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

pipx安装

pipx 是一個专门用于安装和管理Python命令行工具的包管理器。是pip installable executables的缩写，它可以让你在虚拟环境中安装Python工具，然后通过命令行直接调用这些工具。

pip install pipx
pipx install poetry
poetry --version

使用

基本使用

创建新项目

poetry new my_project

会在new_project目录下生成一个新的项目，包含了pyproject.toml文件

或者也可以在你的项目中运行

poetry init

他会把你的项目变成一个poetry项目，生成pyproject.toml文件

进入虚拟环境

使用以下命令进入虚拟环境，

如果虚拟环境不存在，他使用设定的Python版本（详见下文<使用不同的Python版本>）创建一个虚拟环境

poetry shell

后边的命令都要先进入虚拟环境才能执行

包管理

安装pyproject.toml中的依赖

poetry install

新增安装包，执行后会安装包，并在pyproject.toml中添加依赖

# 安装包xxx1 xxx2, 会根据依赖计算一个适合的最新的版本
poetry add xxx1 xxx2
# 安装包xxx3,要求版本>=2.32.2, 会安装满足要求的最新版本
poetry add "requests>=2.32.2"
# 安装包xxx3,要求版本>=2.32.2, <3.0, 会安装满足要求的最新版本
poetry add "requests>=2.32.2,<3.0"
# 安装包xxx3,要求版本必须为2.32.2
poetry add "requests==2.32.2"

卸载包， 执行后会卸载包，并在pyproject.toml中删除依赖

poetry remove xxx1 xxx2

更新包

假设先前安装了一个包要求版本大于3.2, 小于4.0, 现在这个包的新版本有3.9，4.0，执行如下命令，将会更新这个包到3.9版本

poetry update

查看当前已安装包的版本

poetry show

当然也可以手动修改pyproject.toml文件，然后执行以下命令安装依赖

poetry lock
poetry install

比如pyproject.toml 中原先requests<=2.32.2,假如修改为requests<=2.31.2,执行上边的命令，会从2.32.2版本的requests降级为2.31.2版本

不进入虚拟环境直接执行命令

可以通过poetry run来执行命令，比如执行项目中的main.py

poetry run python main.py

如果虚拟环境不存在，poetry会自动创建一个虚拟环境

虚拟环境管理

查看当前虚拟环境

poetry env info

退出虚拟环境

exit

查看当前存在的虚拟环境

poetry env list

删除虚拟环境

# xxx是env list中显示的名字
poetry env remove xxx
# 删除全部虚拟环境
poetry env remove --all

镜像源配置

poetry暂时没提供原生的全局镜像源配置，只能在每个项目中配置

如果要配置全局镜像源，需要借助第三方的插件

仓库级配置

poetry source add --priority=primary mirrors https://pypi.tuna.tsinghua.edu.cn/simple/

全局配置

详见
https://github.com/arcesium/poetry-plugin-pypi-mirror?tab=readme-ov-file

poetry self add poetry-plugin-pypi-mirror

然后在~/.config/poetry/config.toml中添加如下内容

[plugins]
[plugins.pypi_mirror]
url = "https://pypi.tuna.tsinghua.edu.cn/simple/"

使用不同的Python版本

使用pyenv管理Python版本

默认poetry使用系统的Python版本，如果你要安装的包需要其他版本的Python，需要预先安装这个版本的Python (这个是跟conda的一个区别，conda会自动安装指定的Python版本，poetry需要自行解决)

官网推荐使用pyenv管理Python版本

# 安装pyenv
curl https://pyenv.run | bash
# poetry获取当前shell中的Python版本，而不是使用poetry自带的Python版本
poetry config virtualenvs.prefer-active-python true

安装pyenv后，需要在~/.bashrc中添加如下内容

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

以下用于解决国内pyenv安装Python时，下载速度慢的问题，设置Python安装镜像为国内的淘宝镜像地址; 需要的话可以在~/.bashrc中追加以下两行

可选的其他镜像地址(配置PYTHON_BUILD_MIRROR_URL环境变量以应用):

• http://yyuu.github.io/pythons/
• https://registry.npmmirror.com/-/binary/python

export PYTHON_BUILD_MIRROR_URL_SKIP_CHECKSUM=1
export PYTHON_BUILD_MIRROR_URL="https://registry.npmmirror.com/-/binary/python"

重载bashrc配置以在当前shell应用上边的命令

source ~/.bashrc

假如需要安装Python3.11，

首先根据官方文档，安装缺失的系统依赖库https://github.com/pyenv/pyenv/wiki#suggested-build-environment

如Ubuntu执行下列命令安装依赖项

sudo apt update; sudo apt install build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev curl git \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

然后可以使用如下命令来安装指定的Python版本了

pyenv install 3.11.0

输入如下，表示安装成功

Downloading Python-3.11.0.tar.xz...
-> https://registry.npmmirror.com/-/binary/python/3.11.0/Python-3.11.0.tar.xz
Installing Python-3.11.0...
Installed Python-3.11.0 to /home/deepwzh/.pyenv/versions/3.11.0
```txt

这个时候用
```shell
pyenv versions

* system (set by /home/deepwzh/.pyenv/version)
  3.11.0

可以看到多了一个新安装的3.11.0的版本

选择使用Python版本

在开始前，先执行

python3 --version

可以得知当前系统的Python版本，这里笔者的是3.12.0

新建一个项目, 执行poetry init, 交互如下，选择的是Python3.11版本

This command will guide you through creating your pyproject.toml config.

Package name [test]:  
Version [0.1.0]:  
Description []:  
Author [weizhonghua <[email protected]>, n to skip]:  
License []:  
Compatible Python versions [^3.12]:  3.11

Would you like to define your main dependencies interactively? (yes/no) [yes] n
Would you like to define your development dependencies interactively? (yes/no) [yes] n
Generated file

[tool.poetry]
name = "test"
version = "0.1.0"
description = ""
authors = ["weizhonghua <[email protected]>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "3.11"


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


Do you confirm generation? (yes/no) [yes] yes

使用pyenv指定要使用的Python版本,这里用我们刚安装的3.11

pyenv local 3.11
pyenv shell

pyenv local命令会在项目目录生成一个.python-version文件，内容为指定的Python版本号

 poetry env info

Virtualenv
Python:         3.11.0
Implementation: CPython
Path:           /home/deepwzh/.cache/pypoetry/virtualenvs/test-wgCpecab-py3.11
Executable:     /home/deepwzh/.cache/pypoetry/virtualenvs/test-wgCpecab-py3.11/bin/python
Valid:          True

Base
Platform:   linux
OS:         posix
Python:     3.11.0
Path:       /home/deepwzh/.pyenv/versions/3.11.0
Executable: /home/deepwzh/.pyenv/versions/3.11.0/bin/python3.11

查看刚才的输出，Virtualenv和Base的Python版本是3.11.0，说明我们成功切换了Python版本

Virtualenv中的Executable是Python的路径，他是一个指向Base的软连接，并不是独立安装的Python

包的发布

待补充

docker中使用

这里提供一个dockerfile的模板

FROM docker.io/python:3.12-slim

RUN pip install poetry -i https://pypi.tuna.tsinghua.edu.cn/simple

WORKDIR /app
COPY pyproject.toml .
COPY poetry.lock .

RUN poetry config virtualenvs.create false && poetry install

COPY . .

ENTRYPOINT ["python", "main.py"]

单独拷贝pyproject.toml和poetry.lock，是为了利用docker的缓存机制，只有在这两个文件改变的时候，才会重新安装依赖

配置virtualenvs.create false是为了不在docker中创建虚拟环境，直接在全局安装，这样就可以直接python main.py来运行而不需要进入虚拟环境