PyCharm 2025.2 Help

配置 Poetry 环境

Poetry 是一个工具,可帮助基于项目依赖项创建 Python 虚拟环境。 您可以声明项目所依赖的库,Poetry 将为您安装和更新它们。

项目依赖记录在 pyproject.toml 文件中,该文件指定所需的包、脚本、插件和 URL。 有关其结构和格式的更多信息,请参阅 pyproject 参考。

要在 PyCharm 中使用 Poetry,您需要 在您的机器上安装它并创建一个特定的 Python 环境。

安装 Poetry

  1. 打开终端(在 macOS 和 Linux 上)或 PowerShell(在 Windows 上),然后执行以下命令:

    curl -sSL https://install.python-poetry.org | python3 -
    (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
    curl -sSL https://install.python-poetry.org | python3 -
  2. 在 macOS 和 Windows 上,安装脚本会建议将包含 poetry 可执行文件的文件夹添加到 PATH 变量中。 通过运行以下命令来完成此操作:

    export PATH="/Users/jetbrains/.local/bin:$PATH"
    $Env:Path += ";C:\Users\jetbrains\AppData\Roaming\Python\Scripts"; setx PATH "$Env:Path"

    别忘了将 jetbrains 替换为您的用户名!

  3. 要验证安装,请运行以下命令:

    poetry --version

    您应该会看到类似 Poetry (version 1.2.0) 的内容。

有关更多信息,请参阅 Poetry 安装说明

创建一个 Poetry 环境

  1. 请执行以下操作之一:

  2. 点击可用解释器列表旁的 添加解释器 链接并选择 添加本地解释器

  3. 以下操作取决于您是想创建一个新的 Poetry 环境还是使用一个现有的环境。

    新的 Poetry 环境
    生成新的 Poetry 环境
    1. 从环境类型列表中选择 Poetry

    2. 从列表中选择基础解释器,或者点击 浏览… 并在您的文件系统中找到 Python 可执行文件。

    3. PyCharm 将检测 Poetry 安装。

      如果 PyCharm 未检测到 Poetry 安装,请点击 通过 pip 安装 poetry ,允许 PyCharm 自动为您安装 Poetry。

      或者,指定 Poetry 可执行文件的位置,或点击 浏览… 浏览查找该文件。

    现有 Poetry 环境
    选择现有的 Poetry 环境
    1. 确保项目目录包含一个 pyproject.toml 文件。

    2. 从列表中选择解释器。

      如果列表中没有所需的解释器,请点击 ,然后在先前配置的 Poetry 环境中浏览所需的 Python 可执行文件。

    所选的 Poetry 环境将用于当前项目。

  4. 点击 确定 完成任务。

如果您在 创建新 Python 项目时选择了 Poetry 环境,PyCharm 将根据项目需求创建 pyproject.toml

每次您修改 pyproject.toml 文件时,PyCharm 会通知您并提供两个操作选项:将更改记录到 poetry.lock 文件中(poetry lock ),或记录更改并安装未满足的需求(poetry update)。

锁定或更新 Poetry

使用 pyproject.toml 创建 Poetry 环境

  1. 当您打开一个包含 pyproject.toml 的项目,但未配置项目解释器时,PyCharm 会建议您设置一个 Poetry 环境。

    检测到 pyproject.toml
  2. PyCharm 将显示 Poetry 可执行文件的路径。 通过点击 确定 确认路径。

  3. 如果 PyCharm 无法自动检测到 Poetry 可执行文件,请手动指定其路径。

一个新的 Poetry 环境将为您的项目配置,并安装列在 pyproject.toml 中的包。

最后修改日期: 2025年 9月 26日