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 PyCharm, you need to install it on your machine and create a specific Python environment.

Install Poetry

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 -
If you have installed Python through the Microsoft Store, replace py with python in the command above.
curl -sSL https://install.python-poetry.org | python3 -
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!
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

Do one of the following:
- Click the Python Interpreter selector and choose Add New Interpreter.
- Press Ctrl+Alt+S to open Settings and go to Project: <project name> | Python Interpreter. Click the Add Interpreter link next to the list of the available interpreters.
- Click the Python Interpreter selector and choose Interpreter Settings. Click the Add Interpreter link next to the list of the available interpreters.
Select Add Local Interpreter.
The following actions depend on whether you want to create a new Poetry environment or to use an existing one.
New Poetry environment
1. Select Poetry from the list of environment types.
2. Select the base interpreter from the list or click and find the Python executable in your file system.
3. If PyCharm doesn't detect the poetry executable, click Install poetry via pip to allow PyCharm to install poetry for you automatically.
  Alternatively, click Select path and choose the required file manually or 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
1. Make sure that the project directory contains a pyproject.toml file.
2. Select the interpreter from the list.
  If the required 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.
Click OK to complete the task.

If you select a Poetry environment when creating a new Python project, PyCharm creates pyproject.toml with the project requirements.

Each time you modify the pyproject.toml file, PyCharm 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).

Create a Poetry environment using pyproject.toml

When you open a project that contains pyproject.toml, but no project interpreter is configured, PyCharm suggests that you set up a Poetry environment.
PyCharm will display the path to the Poetry executable. Confirm the path by clicking OK.
If PyCharm cannot autodetect the Poetry executable, specify the path to it manually.

A new Poetry environment will be configured for your project and the packages listed in pyproject.toml will be installed.

Last modified: 13 November 2024