Skip to main content

How to Manage Your Python Project Using Poetry

· 8 min read

前段时间在写 tidbcloudy(一个 TiDB Cloud Python SDK)的时候用到了 Poetry 来管理依赖以及发布到 PyPI。经历了五次小版本的迭代,感觉 Poetry 时常让我有一种“写 SDK 也不难,发版也可以很简单”的错觉,所以决定记录一下我是如何使用 Poetry 来完成我的第一个 SDK 的。

Poetry 是什么

Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. Poetry offers a lockfile to ensure repeatable installs, and can build your project for distribution.

Poetry 是一个管理 Python 依赖的工具,它可以帮助你声明你的项目依赖的库,然后帮你管理(安装/更新)它们。Poetry 提供了一个 poetry.lock 文件来确保可复现,也可以将你的项目打包。

安装 Poetry

下面以在 Ubuntu 20.04 上安装及使用 Poetry 为例。详细的安装方法,请参考 Poetry 官方文档

curl -sSL | python3 -


Retrieving Poetry metadata

# Welcome to Poetry!

This will download and install the latest version of Poetry,
a dependency and package manager for Python.

It will add the `poetry` command to Poetry's bin directory, located at:


You can uninstall at any time by executing this script with the --uninstall option,
and these changes will be reverted.

Installing Poetry (1.2.2): Creating environment
Installing Poetry (1.2.2): Done

Poetry (1.2.2) is installed now. Great!

You can test that everything is set up by executing:

`poetry --version`

查看 Poetry 版本:

poetry --version


Poetry (version 1.2.2)

开启 tab 自动补全(可选)

poetry 命令支持在 Bash、Fish 和 Zsh 中开启 tab 自动补全功能。详细的开启方法,请参考 Poetry 官方文档


在写这篇文章的时候,测试发现 poetry Bash 自动补全无法正常使用。具体 issue 可以关注 #6835


查看当前使用的 shell:

echo $SHELL

下面以开启 Zsh 自动补全为例:

poetry completions zsh > ~/.zfunc/_poetry


$ poetry [TAB]
about -- Shows information about Poetry.
add -- Adds a new dependency to pyproject.toml.
build -- Builds a package, as a tarball and a wheel by default.
cache -- Interact with Poetry's cache
check -- Checks the validity of the pyproject.toml file.
config -- Manages configuration settings.
debug -- Debug various elements of Poetry.
env -- Interact with Poetry's project environments.
export -- Exports the lock file to alternative formats.
help -- Display the manual of a command


使用 poetry new 命令创建并初始化一个新项目 tidbcloudy

poetry new tidbcloudy


Created package tidbcloudy in tidbcloudy

查看新创建的 tidbcloudy 项目目录结构:

$ tree tidbcloudy
├── pyproject.toml
├── tests
│   └──
└── tidbcloudy

2 directories, 4 files



  • pyproject.toml:项目配置文件,包含项目的名称、版本、作者等项目基本信息以及项目的依赖信息等。详细说明可参考 Poetry 官方文档

    name = "tidbcloudy"
    version = "0.1.0"
    description = ""
    authors = ["Oreo <[email protected]>"]
    readme = ""

    python = "^3.8"

    requires = ["poetry-core"]
    build-backend = "poetry.core.masonry.api"
  • tests:单元测试文件夹

  • tidbcloudy:项目源码文件夹


pyproject.toml 文件中,tool.poetry.dependencies 字段用于管理项目的依赖。你可以通过修改该字段或使用 poetry 命令来管理依赖。


tidbcloudy 是一个 TiDB Cloud SDK,需要使用 requests 发送 HTTP 请求。下面提供了直接修改 pyproject.toml 文件和使用 poetry add 命令两种方式:

requests = "^2.27.1"


在完成项目依赖的编辑之后,你可以使用 poetry install 命令安装 pyproject.toml 中的依赖:

poetry install

在第一次执行 poetry install 时,该命令会生成 poetry.lock 文件,用于锁定依赖的版本,实现可复现的构建。当项目中已经存在 poetry.lock 文件时,poetry 会根据 pyproject.toml 中的依赖名称和 poetry.lock 中具体的版本及 Hash 等信息来安装依赖。


如果你通过编辑 pyproject.toml 文件来更新依赖,可能会出现 pyproject.tomlpoetry.lock 文件不一致的情况,你可以通过如下方式解决:


你可以通过修改 pyproject.toml 文件或使用 poetry version 来管理项目版本。

version = "0.1.1"


下面以发布 tidbcloudy 项目到 PyPI 为例。

配置 token

参考 PyPI 官方文档 申请你的 PyPI token,然后使用 poetry config 命令配置:

poetry config pypi-token.pypi my-token


使用 poetry build 命令打包:

poetry build


Building tidbcloudy (0.1.1)
- Building sdist
- Built tidbcloudy-0.1.1.tar.gz
- Building wheel
- Built tidbcloudy-0.1.1-py3-none-any.whl

如果遇到 [Errno 2] No such file or directory: 'python' 错误,可以参考 poetry/issue/6841 执行如下命令:

rm -rf $(poetry config virtualenvs.path)/*


使用 poetry publish 命令上传:

poetry publish

上传完成后,你可以通过 PyPI 网站查看你的项目,以及使用 pip install 命令进行安装:

pip install tidbcloudy