Aqua Help

Configure a Poetry environment

Poetry is a tool that facilitates creating a Python virtual environment based on the project dependencies. You can declare the libraries your project depends on, and Poetry will install and update them for you.

Project dependencies are recorded in the pyproject.toml file that specifies required packages, scripts, plugins, and URLs. See the pyproject reference for more information about its structure and format.

To use Poetry in Aqua, you need to install it on your machine and create a specific Python environment.

Install Poetry

  1. Open Terminal (on macOS and Linux) or PowerShell (on Windows) and execute the following command:

    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. On macOS and Windows, the installation script will suggest adding the folder with the poetry executable to the PATH variable. Do that by running the following command:

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

    Don't forget to replace jetbrains with your username!

  3. To verify the installation, run the following command:

    poetry --version

    You should see something like Poetry (version 1.2.0).

For more information, refer to the Poetry Installation Instructions.

Create a Poetry environment

  1. Navigate to File | Project Structure or press Ctrl+Alt+Shift+S.

  2. In the Project Structure dialog, select SDKs under the Platform Settings section, click Add a new SDK, and choose Add Python SDK from the popup menu.

    Adding a new Python SDK
  3. In the left-hand pane of the Add Python Interpreter dialog, select Poetry Environment.

    creating a poetry environment
  4. The following actions depend on whether you want to create a new Poetry environment or to use an existing one.

    New Poetry environment
    • Select Poetry Environment.

    • Choose the base interpreter from the list, or click Choose the base interpreter and find the desired Python executable in your file system.

    • If your project contains pyproject.toml, you can choose whether you want to install the packages listed in it by enabling or disabling the Install packages from pyproject.toml checkbox. By default, the checkbox is enabled.

    • If Aqua doesn't detect the poetry executable, specify the following path in the dialog, replacing jetbrains with your username:

      /Users/jetbrains/Library/Application Support/pypoetry/venv/bin/poetry
      C:\Users\jetbrains\AppData\Roaming\pypoetry\venv\Scripts\poetry.exe
      /home/jetbrains/.local/bin/poetry
    Existing Poetry environment
    • Make sure that the project directory contains a pyproject.toml file.

    • Select Existing environment. Then expand the Interpreter list and choose the desired interpreter.

    • If the desired interpreter is not on the list, click, and then browse for the Python executable within the previously configured Poetry environment.

    The selected Poetry environment will be reused for the current project.

  5. Click OK to complete the task.

When you configure a new Poetry environment, Aqua creates pyproject.toml with the project requirements.

Each time you modify the pyproject.toml file, Aqua notifies you and offers two actions: to record the changes in the poetry.lock file (poetry lock) or to record the changes and install the unsatisfied requirements (poetry update).

Last modified: 07 March 2024