Install & Compatibility
Where this runs
tested against v3.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.628s · 21.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.1s · import 0.548s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GerritClient
✓ from gerrit import GerritClient
✗ from gerrit import Gerrit
While older examples or the GitHub README might show 'from gerrit import Gerrit', 'GerritClient' is the consistently used class in current documentation and examples for initializing the client.
This quickstart demonstrates how to initialize the `GerritClient` and perform a basic operation, such as listing projects. It uses environment variables for authentication credentials, which is recommended for security. Ensure your Gerrit instance uses HTTP Basic Authentication and you have an HTTP password configured (not an SSH password).
import os
from gerrit import GerritClient
GERRIT_HOST = os.environ.get('GERRIT_HOST', 'http://review.example.com')
GERRIT_USERNAME = os.environ.get('GERRIT_USERNAME', 'your_username')
GERRIT_PASSWORD = os.environ.get('GERRIT_PASSWORD', 'your_http_password')
try:
# Initialize the Gerrit client with HTTP Basic Authentication
client = GerritClient(
base_url=GERRIT_HOST,
username=GERRIT_USERNAME,
password=GERRIT_PASSWORD
)
# Example: List projects
projects = client.projects.list(limit=5)
print(f"Successfully connected to Gerrit. Found {len(projects)} projects:")
for project in projects:
print(f"- {project['name']}")
# Example: Get a specific change (replace with a real change ID/number)
# Note: Gerrit REST API often expects the 'id' of a change, not just the change number.
# You might need to fetch a list of changes first to get an ID.
# change = client.changes.get('12345') # Example change number
# print(f"Change {change['id']}: {change['subject']}")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure GERRIT_HOST, GERRIT_USERNAME, and GERRIT_PASSWORD are set correctly.")
Debug
Known issues
breakingPython 2.x support has been dropped. Versions of python-gerrit-api 3.x and above require Python 3.8 or newer.fixEnsure your project is running on Python 3.8+ and update your dependencies. Older versions of the library (2.x) might support Python 2.7, but are not actively maintained.
affects: 3.x.x and later
gotchaGerrit REST API authentication requires an HTTP password, which is distinct from an SSH password. Authenticated calls also typically require prefixing the endpoint URL with '/a/' (e.g., /a/projects/). The library handles the '/a/' prefix automatically when `username` and `password` are provided to `GerritClient`.fixEnsure you are using the correct HTTP password for your Gerrit user, which can often be generated or found in your Gerrit user settings. The library typically adds the '/a/' prefix for authenticated requests automatically.
affects: All versions
gotchaThe API structure and available methods within `GerritClient` may have evolved between major versions (e.g., from 2.x to 3.x). While not explicitly documented as breaking changes for the client library, internal Gerrit server API changes (like those in Gerrit 3.0.x) can necessitate updates to the client library and its usage patterns.fixRefer to the specific release notes or the latest documentation on GitHub/ReadTheDocs when upgrading major versions. Test your code thoroughly after major version upgrades to catch any API changes.
affects: 2.x.x to 3.x.x migration
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'gerritapi'
The `python-gerrit-api` package has not been installed in the current Python environment.
fixpip install python-gerrit-api
ImportError: cannot import name 'Gerrit' from 'gerritapi'
The primary class for interacting with the Gerrit API in `python-gerrit-api` is `GerritAPI`, not `Gerrit`.
fixfrom gerritapi import GerritAPI
gerritapi.exceptions.GerritAPIException: Authentication failed
The provided authentication credentials (username, password, or other tokens) for the Gerrit server are incorrect or insufficient.
fixfrom gerritapi import GerritAPI
gerrit_host = "https://your-gerrit-instance.com"
gerrit_user = "your_correct_username"
gerrit_password = "your_correct_password"
g = GerritAPI(gerrit_host, auth=(gerrit_user, gerrit_password))
requests.exceptions.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed
The Gerrit server's SSL certificate cannot be verified by the system's trust store, often due to a self-signed or internal CA certificate.
fixfrom gerritapi import GerritAPI
# Use verify=False to disable SSL certificate verification (use with caution in production)
g = GerritAPI("https://your-gerrit-instance.com", auth=("user", "password"), verify=False) Upgrade
Version history
3.1.0latest on PyPI · released Mar 14, 2026
Audit
Dependencies
requestsrequiredUsed for making HTTP requests to the Gerrit REST API.