Python plugin¶

The Python plugin builds charms written in Python. It’s typically used in conjunction with the Operator framework.

Keys¶

This plugin provides the following unique keys.

python-requirements¶

Type: list of strings

List of paths to requirements files.

Use this key when dependencies must be installed from one or more explicit requirements files, such as requirements.txt. The plugin does not automatically select a requirements file from the source tree; each file must be listed here.

A part does not need this key when its dependencies are already declared by the project metadata used during package installation. For example, when the source contains a setup.py or pyproject.toml file, the plugin installs the project and pip resolves the dependencies declared by the package itself. That metadata may also come from configuration files such as setup.cfg.

python-constraints¶

Type: list of strings

List of paths to constraint files.

python-packages¶

Type: list

A list of dependencies to install from PyPI. If needed, pip, setuptools and wheel can be upgraded here.

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. These are defined in the following sections.

PARTS_PYTHON_INTERPRETER¶

Default: python3

The interpreter binary to search for in PATH.

PARTS_PYTHON_VENV_ARGS¶

Additional arguments for venv.

Dependencies¶

This plugin creates a Python virtual environment in the venv directory of your charm using the version of Python included with your base and the requirements files provided in the python-requirements key.

Note

The python plugin prevents pip from installing dependencies for the required packages. Therefore, requirements must include indirect dependencies as well as direct dependencies. It is recommended that you use a tool such as pip-compile or uv to manage the contents of your requirements.txt file.

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 pip to install the required Python packages specified by the python-requirements, python-constraints and python-packages keys.
It copies any existing src and lib directories from your charm project into the final charm.

Example¶

The following project file can be used with a standard charm structure to build a charm for Ubuntu 26.04 LTS:

name: my-charm
type: charm
title: My Python charm
summary: An operator charm that uses the python plugin
description: |
  An operator charm using the Python plugin.
base: ubuntu@26.04
platforms:
  amd64:
parts:
  my-charm:
    source: .
    plugin: python
    python-requirements:
      - requirements.txt