Installing the LINSTOR Python API Client Library

The python-linstor package provides the Python client library used for interfacing with the LINSTOR® REST API. The package is published on the Python Package Index (PyPI). Its upstream source is the linstor-api-py repository on GitHub.

There are a few common reasons to install python-linstor outside of a LINSTOR cluster:

1. The modules in the linbit.linstor Ansible collection require python-linstor on the Ansible control node (often your laptop or workstation).

2. The LINSTOR client utility also requires python-linstor. The LINSTOR client utility can be installed on a workstation or laptop to manage LINSTOR externally through CLI commands.

3. Custom Python scripts and automation using the LINSTOR API directly, such as a containerized application querying a LINSTOR cluster in Kubernetes.

💡 TIP: The Ansible control node is a LINSTOR client itself, using the same shared API as other LINSTOR components. LINSTOR Ansible modules delegate task execution to localhost by default.

Installing the client requires a supported Python 3 interpreter and pip.

When you install python-linstor for Ansible, install it into the same Python interpreter that runs ansible. If ansible runs from a virtual environment or from pipx, install python-linstor into that same environment.

The following table summarizes the installation method for each distribution:

💡 TIP: Recent macOS releases do not bundle a Python interpreter, so install Python 3 with Homebrew or the python.org installer.

To install python-linstor for your user only, run the following command:

pip install --user --break-system-packages python-linstor

📝 NOTE: Most current platforms mark the system Python as externally managed, so the --break-system-packages option is required, or use a Python virtual environment instead.

If you are using Ubuntu LTS, install python-linstor from the public LINBIT personal package archive (PPA).

Add the PPA and install the package:

add-apt-repository -y ppa:linbit/linbit-drbd9-stack
apt update
apt -y install python-linstor

You can use a LINSTOR cluster node as the Ansible control node, where the LINSTOR node itself is localhost, running the Ansible playbooks directly.

💡 TIP: LINSTOR cluster nodes likely already have python-linstor installed as a system package due to linstor-client package dependencies.

The linbit.linstor Ansible collection assumes the use of localhost when using LINSTOR Ansible modules.

Ansible can also delegate tasks to select hosts. Delegating LINSTOR module tasks to a member of a LINSTOR cluster bypasses the need to install python-linstor on the Ansible control node itself.

For example, delegate a LINSTOR module task to a LINSTOR controller node (controller-0):

- name: Disable auto-eviction on a specific node
  linbit.linstor.node:
    name: node-1
    properties:
      DrbdOptions/AutoEvictAllowEviction: "false"
  # Use python-linstor directly on controller-0
  delegate_to: controller-0
  run_once: true  # noqa: run-once[task]

Both of these methods bypass the need to install python-linstor outside of the LINSTOR cluster itself.

Written by RR, 2026-06-04.

Reviewed by MAT, 2026-06-09.