Poetry plugin¶

The Poetry plugin can be used for Python charms written using Poetry and the Operator framework.

Keywords¶

This plugin uses the common plugin keywords as well as those for sources.

Additionally, this plugin provides the plugin-specific keywords defined in the following sections.

poetry-export-extra-args:¶

Type: list of strings

Extra arguments to pass at the end of the poetry `export command`_.

poetry-pip-extra-args:¶

Type: list of strings

Extra arguments to pass to pip install when installing dependencies.

poetry-with:¶

Type: list of strings

Extra dependency groups to use other than the defaults.

python-keep-bins¶

Type: boolean Default: False

Whether to keep python scripts in the virtual environment’s bin directory.

Environment variables¶

This plugin also sets environment variables in the build environment. User-set environment variables will override these values. Users may also set environment variables to configure Poetry using the build-environment key.

PARTS_PYTHON_INTERPRETER¶

Default value: python3

Either the interpreter binary to search for in PATH or an absolute path to the interpreter (e.g. ${CRAFT_STAGE}/bin/python).

PARTS_PYTHON_VENV_ARGS¶

Default value: (empty string)

Additional arguments passed to python -m venv.

Dependencies¶

Python¶

By default this plugin uses the system Python when available and appropriate to use, using the same logic as the Python plugin. If a different interpreter is desired, it must be made available in the build environment (including the venv module) and its path must be included in the PATH environment variable. Use of python3-<python-package> in stage-packages will force the inclusion of the Python interpreter.

Poetry¶

By default, this plugin gets Poetry from the python3-poetry package on the build system. If that is not desired (for example, if a newer version of Poetry is required), a poetry-deps part can install poetry in the build system. Any parts that use the Poetry plugin must run after the poetry-deps part:

parts:
  poetry-deps:
    plugin: nil
    build-packages:
      - curl
      - python3
    build-environment:
      - POETRY_VERSION: "1.8.0"
    override-pull: |
      curl -sSL https://install.python-poetry.org | python3 -
  my-project:
    plugin: poetry
    source: .
    after: [poetry-deps]

How it works¶

During the build step, the plugin performs the following actions:

It creates a virtual environment in the ${CRAFT_PART_INSTALL}/venv directory.
It uses poetry export to create a requirements.txt in the project’s build directory.
It uses pip to install the packages referenced in requirements.txt into the virtual environment. Undeclared dependencies are ignored.
It copies any existing src and lib directories from your charm project into the final charm.
It runs pip check to ensure the virtual environment is consistent.

Example¶

The following charmcraft.yaml file can be used with a poetry project to build the charm for Ubuntu 24.04:

name: my-charm
type: charm
title: My poetry charm
summary: An operator charm using Poetry.
description: |
  An operator charm that uses Poetry for its project.
base: [email protected]
platforms:
  amd64:
parts:
  my-charm:
    source: .
    plugin: poetry