PyCharm 2025.1 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. 请执行以下操作之一:

    • 点击 Python Interpreter 选择器 并选择 添加新的解释器

    • Ctrl+Alt+S 以打开 设置 并转到 项目:<项目名称> | Python 解释器。 点击可用解释器列表旁的 添加解释器 链接。

    • 点击 Python Interpreter 选择器 并选择 解释器设置。 点击可用解释器列表旁的 添加解释器 链接。

  2. 请选择 添加本地解释器

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

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

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

    3. 如果 PyCharm 未检测到 poetry 可执行文件,请点击 通过 pip 安装 poetry 以允许 PyCharm 自动为您安装 poetry。

      或者,点击 选择路径 并手动选择所需的文件,或在对话框中指定以下路径,并将 jetbrains 替换为您的用户名:

      /Users/jetbrains/Library/Application Support/pypoetry/venv/bin/poetry
      C:\Users\jetbrains\AppData\Roaming\pypoetry\venv\Scripts\poetry.exe
      /home/jetbrains/.local/bin/poetry
    现有 Poetry 环境
    选择现有的 Poetry 环境
    1. 确保项目目录包含一个 pyproject.toml 文件。

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

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

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

  4. 点击 OK 完成任务。

如果您在 创建新 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 可执行文件的路径。 通过点击 OK 确认路径。

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

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

最后修改日期: 2025年 4月 23日