当前位置：首页 > news >正文

从零到一：快速上手 Poetry——Python 项目管理的利器

news 来源：原创 2025/6/23 6:41:10

在 Python 项目开发中，包管理、依赖管理和虚拟环境的创建一直是开发者们经常面对的难题。传统上，开发者通常会使用 pip、virtualenv 或者 conda 来处理这些问题。然而，随着 Python 项目复杂度的增加，传统工具往往显得力不从心，这时 Poetry 应运而生，成为一个更加现代化、简洁和高效的工具。

本文将从零开始，带领你快速上手 Poetry，介绍如何使用 Poetry 来管理 Python 项目，包括安装、配置、依赖管理、虚拟环境和打包发布等。

什么是 Poetry？

Poetry 是一个 Python 项目的管理工具，它集成了依赖管理、虚拟环境管理、包打包、发布等功能。Poetry 旨在简化开发者的工作流程，让你能够轻松地管理项目的依赖，确保环境的一致性，并快速创建和发布 Python 包。

Poetry 的关键优势是：

自动创建和管理虚拟环境。
精确的依赖解析，避免版本冲突。
使用 pyproject.toml 文件简化配置和管理。
支持打包、发布、安装等一体化功能。

Poetry 的安装

首先，你需要在你的系统上安装 Poetry。你可以使用官方推荐的安装命令来进行安装：

1. 安装 Poetry

打开终端（命令行），并运行以下命令来安装 Poetry：

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

或者，如果你是 Windows 用户，你可以使用以下 PowerShell 命令：

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicP) | python -

安装完成后，可以通过以下命令确认是否安装成功：

poetry --version

如果安装成功，会输出 Poetry 的版本号。

创建一个新项目

Poetry 提供了一个非常简洁的命令来初始化新的 Python 项目，它会自动创建必要的文件结构和配置。

2. 创建新项目

在终端中运行以下命令，创建一个新的 Python 项目：

poetry new my_project

这将会在当前目录下创建一个名为 my_project 的文件夹，并且自动生成一个基本的 Python 项目结构。你会看到如下文件和文件夹：

my_project/
├── my_project/
│   └── __init__.py
├── pyproject.toml
└── tests/
    └── __init__.py

pyproject.toml：这是 Poetry 项目的核心配置文件，所有关于项目的元数据（如依赖、版本等）都会写在这个文件里。
my_project/__init__.py：项目的 Python 源代码文件。
tests/：包含测试代码的文件夹，Poetry 默认为你创建了一个简单的测试文件夹。

3. 进入项目目录

cd my_project

管理项目依赖

Poetry 提供了强大的依赖管理功能，让你可以精确控制项目所需的包版本，并自动处理依赖的版本冲突。通过一些简单的命令，你可以轻松地安装、更新和管理项目依赖。

4. 初始化项目依赖

如果你已经有一个现有的项目，并且希望使用 Poetry 来管理其依赖，可以通过以下命令来初始化项目并创建 pyproject.toml 文件：

poetry init -n

-n 参数表示自动跳过交互式提示，直接创建文件。这将会生成一个 pyproject.toml 文件，并为你提供一个基础的依赖结构。

5. 添加依赖

当你需要向项目中添加一个新的依赖时，可以使用 poetry add 命令。举个例子，如果你想添加 requests 库，可以运行以下命令：

poetry add requests

这会将 requests 库添加到 pyproject.toml 中，同时 Poetry 会根据项目的需要自动解决依赖版本。

如果你需要添加特定版本的依赖，可以使用类似下面的命令：

poetry add requests@2.25.0

6. 安装所有依赖

如果你从其他地方克隆了一个项目，并且需要安装所有的依赖，可以使用 poetry install 命令。它会根据 pyproject.toml 和 poetry.lock 文件安装所有的项目依赖：

poetry install

该命令会自动创建并激活虚拟环境，确保你在隔离的环境中安装依赖，从而避免全局包的冲突。

7. 安装开发依赖

有些依赖是只在开发时需要的，比如测试框架。Poetry 允许你使用 --dev 参数来安装开发依赖：

poetry add --dev pytest

此时，pytest 将只会在开发环境中安装，不会影响生产环境的依赖。

8. 使用其他 Python 版本

Poetry 允许你指定使用特定的 Python 版本。如果你已经安装了多个 Python 版本，可以通过 poetry env use 命令指定 Python 解释器的路径。例如：

poetry env use "path/to/your/python.exe"

这个命令会强制 Poetry 使用你指定的 Python 解释器来创建虚拟环境。

9. 使用 `requirements.txt`

如果你的项目原本使用了 requirements.txt 来管理依赖，并且你想迁移到 Poetry 上，可以使用以下命令来安装 requirements.txt 中的所有依赖：

poetry run pip install -r requirements.txt

这会在 Poetry 的虚拟环境中使用 pip 安装 requirements.txt 中列出的所有依赖项，并确保它们与项目的其他依赖兼容。

10. 更新依赖

随着项目的发展，依赖可能会有新的版本发布。你可以使用 poetry update 命令来更新所有依赖到最新的兼容版本：

poetry update

这将会根据你的 pyproject.toml 文件中的版本要求，更新所有已安装的依赖。

11. 查看项目的依赖

如果你想查看当前项目的所有依赖，可以使用：

poetry show

这将列出所有直接和间接的依赖项，并提供每个包的版本和其他详细信息。

12. 删除依赖

如果某个依赖不再需要，你可以使用 poetry remove 命令来删除它：

poetry remove requests

这会将 requests 从 pyproject.toml 文件和 poetry.lock 文件中移除，并卸载它。

通过这些命令，Poetry 使得依赖管理变得更加高效和便捷。无论是添加、更新、安装开发依赖，还是使用指定的 Python 版本，Poetry 都提供了灵活的工具来帮助你管理项目的依赖和虚拟环境。

虚拟环境管理

Poetry 自动为每个项目创建和管理虚拟环境，这样就能确保你的项目始终在隔离的环境中运行，避免了全局安装包可能带来的冲突。

13. 查看虚拟环境

如果你想查看 Poetry 创建的虚拟环境，可以运行以下命令：

poetry env list

它会列出当前项目所使用的虚拟环境。你还可以通过 poetry env use 来切换 Python 版本。

14. 激活虚拟环境

你可以通过以下命令激活虚拟环境：

poetry shell

这会激活虚拟环境，并进入一个新的 shell，你可以在其中运行 Python 命令，测试代码等。

运行项目

Poetry 允许你直接在虚拟环境中运行命令，而不需要先手动激活虚拟环境。

15. 使用 Poetry 运行命令

如果你想直接运行 Python 脚本，可以使用以下命令：

poetry run python my_project/script.py

poetry run 会确保命令在 Poetry 管理的虚拟环境中运行。

打包和发布

当你的项目开发完成后，Poetry 还可以帮助你将项目打包并发布到 PyPI 或其他 Python 包管理平台。

16. 打包项目

首先，使用以下命令来构建项目的发行版：

poetry build

这将会生成 .tar.gz 和 .whl 格式的包，存放在 dist/ 文件夹中。

17. 发布到 PyPI

如果你准备将项目发布到 PyPI，可以使用以下命令：

poetry publish --repository

 pypi

当然，在发布前，你需要配置 PyPI 的认证信息，可以通过 poetry config 命令进行配置。

常用 Poetry 命令总结

命令	功能
`poetry new <project_name>`	创建一个新的 Python 项目
`poetry add <package>`	添加依赖包到项目中
`poetry install`	安装项目的所有依赖
`poetry update`	更新项目依赖到最新版本
`poetry shell`	启动项目虚拟环境的 shell
`poetry run <command>`	在虚拟环境中运行指定命令
`poetry build`	打包项目
`poetry publish`	发布项目到 PyPI
`poetry env list`	查看虚拟环境