Install & Compatibility
Where this runs
tested against v? · pip install
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.95 runs
build_error
glibcpy 3.10–3.95 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
kerberos
✓ import kerberos
This quickstart demonstrates how to initialize a Kerberos client context and generate the first authentication token using `pykerberos`. It simulates the client-side of a GSSAPI negotiation flow. To run this, you'll typically need an active Kerberos ticket (e.g., obtained via `kinit`) and the correct service principal for your target service. Remember to install system Kerberos development libraries before installing pykerberos.
import kerberos
import os
try:
# Service principal for the target service (e.g., HTTP service on a host)
# Replace 'HTTP/server.example.com@REALM.COM' with your actual service principal.
# For a runnable example, we use an environment variable.
service_principal = os.environ.get('KERBEROS_SERVICE_PRINCIPAL', 'HTTP/fakeserver.example.com@FAKE.REALM')
# Initialize a Kerberos client context
# rc: return code (0 for success, non-zero for error)
# vc: client context handle (opaque object)
rc, vc = kerberos.authGSSClientInit(service_principal)
if rc == kerberos.AUTH_GSS_COMPLETE:
print(f"Successfully initialized Kerberos client context for {service_principal}")
# Perform the first step of GSS-API negotiation
# This generates a token to send to the server.
# The input 'challenge' is empty for the first step.
rc_step, client_token = kerberos.authGSSClientStep(vc, "")
if rc_step == kerberos.AUTH_GSS_COMPLETE:
print(f"Generated client token (to send to server): {client_token[:60]}...")
print("Kerberos client authentication flow started.")
print("Next, send this token to your server and process its response with authGSSClientStep.")
else:
print(f"Kerberos client step failed with return code: {rc_step}")
# Clean up the client context when done
kerberos.authGSSClientClean(vc)
print("Kerberos client context cleaned up.")
else:
print(f"Failed to initialize Kerberos client context for {service_principal}. Return code: {rc}")
print("Possible reasons: missing kinit ticket, incorrect service principal, or system Kerberos setup issues.")
except kerberos.GSSError as e:
print(f"Kerberos GSSAPI Error: {e}")
print("Make sure you have Kerberos development libraries (e.g., krb5-devel) installed and KDC is reachable.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Errors
Common errors & fixes
fatal error: Python.h: No such file or directory
The pykerberos package compiles a C extension during installation, requiring the Python development headers to be present on the system.
fixInstall the Python development headers using your system's package manager (e.g., `sudo apt-get install python3-dev` on Debian/Ubuntu, `sudo yum install python3-devel` on RHEL/CentOS).
gssapi/gssapi.h: No such file or directory
The pykerberos library depends on the underlying Kerberos GSSAPI development headers, which are not installed by default on some systems.
fixInstall the Kerberos GSSAPI development libraries using your system's package manager (e.g., `sudo apt-get install libkrb5-dev` on Debian/Ubuntu, `sudo yum install krb5-devel` on RHEL/CentOS).
No Kerberos credentials available
The application is attempting to use Kerberos authentication, but a valid Kerberos ticket (obtained via `kinit`) is either missing or has expired in the user's credential cache.
fixObtain a Kerberos ticket using the `kinit` command and verify its presence with `klist` before running the application.
ModuleNotFoundError: No module named 'kerberos'
The pykerberos package is not correctly installed or is not accessible in the Python environment where the code is being executed.
fixEnsure `pykerberos` is installed in the active Python environment using `pip install pykerberos`. Verify the installation with `python -c "import kerberos"`.
sh: krb5-config: command not found
This error occurs during installation when the `krb5-config` utility, which is part of the Kerberos development tools, is missing from the system's PATH.
fixInstall the Kerberos development libraries which include `krb5-config` using your system's package manager (e.g., `sudo apt-get install libkrb5-dev` on Debian/Ubuntu, `sudo yum install krb5-devel` on RHEL/CentOS).
Upgrade
Version history
1.2.4latest on PyPI · released Mar 9, 2022
Audit
Dependencies
krb5-develrequiredRequires system-level Kerberos development headers for compilation (e.g., on RHEL/CentOS/Fedora).
libkrb5-devrequiredAlternative system-level Kerberos development headers for Debian/Ubuntu.
krb5requiredFor macOS, install via Homebrew along with Xcode Command Line Tools for compilation.