---
id: patroni
version: "4.1.5"
license: The MIT License
license_treatment: permissive
maintenance: active
---

# patroni — PostgreSQL High-Available orchestrator and CLI

License: permissive · Maintenance: active · Downloads: 94.0K/mo

## What it is and what it does

Patroni is a Python orchestration framework that automates PostgreSQL high-availability cluster management by coordinating replica promotion, failover, and configuration across multiple nodes using a distributed consensus store. It supports PostgreSQL 9.3 to 18 and integrates with etcd, Consul, ZooKeeper, Kubernetes, and Raft as its backing configuration and state store.

You deploy Patroni on each PostgreSQL node in your cluster; it handles leader election, streaming replication setup, and automatic failover when the primary becomes unavailable. It includes HAProxy integration for a single application endpoint and supports both asynchronous and synchronous replication modes. Configuration is YAML-based with environment variable overrides, and the package includes a REST API for monitoring and control.

Use it for:

- Automate failover and replica promotion in multi-node PostgreSQL deployments without manual intervention.
- Manage PostgreSQL cluster state and configuration consistently across nodes using etcd or Consul as a distributed store.
- Integrate PostgreSQL high availability with Kubernetes by running Patroni natively on K8s clusters.
- Set up streaming replication with automatic synchronization and durability guarantees across geographically distributed replicas.
- Monitor and control PostgreSQL cluster health and member status via REST API from external orchestration tools.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Patroni orchestrates PostgreSQL high-availability clusters using distributed configuration stores like etcd, Consul, ZooKeeper, or Kubernetes to manage failover, replication, and cluster state.

Yes. Patroni is production-stable (Development Status 5), actively maintained with recent releases, has no known vulnerabilities, and low install friction. It is the standard choice for PostgreSQL HA orchestration in environments using etcd, Consul, ZooKeeper, or Kubernetes. Install it if you need automated failover and cluster coordination; skip it if you manage PostgreSQL replication manually or use a managed database service.

## Install

pip install patroni
uv add patroni
poetry add patroni

## Installing patroni

Before you install: Low install friction with a pure-Python wheel and eight straightforward runtime dependencies. Actively maintained with a recent release (2 days old) and 8656 GitHub stars, indicating a mature and well-supported project.

License in practice: MIT License (permissive) places no restrictions on use, modification, or redistribution in proprietary or open-source contexts.

Quickstart:

pip install patroni[etcd3]

Then configure a postgres0.yml file and run:
./patroni.py postgres0.yml

Patroni will manage PostgreSQL replication and failover via your chosen DCS.

Requires a running distributed configuration store (etcd, Consul, ZooKeeper, or Kubernetes) and a PostgreSQL driver (psycopg, psycopg2, or psycopg2-binary) installed separately.

Verify before relying:

- Whether Python 3.11+ memory issue (mentioned in description) affects typical deployments or only those with strict vm.overcommit_memory=2 settings.
- Performance characteristics and scalability limits for clusters beyond three nodes.
- Whether Citus extension integration (noted as available since 3.0) is production-ready or experimental.

## Package facts

- License: The MIT License (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 94.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

postgresql high availability clustering, postgres ha orchestration, distributed postgres failover, postgresql cluster management, postgres replication automation, etcd consul zookeeper postgres, kubernetes postgres operator, postgres-ha, cluster-orchestration, distributed-consensus

[View on SkillFed](https://skillfed.io/packages/patroni) · [View on PyPI](https://pypi.org/project/patroni/)