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.
auth
✓ import winkerberos
# ...
context = winkerberos.auth(service_principal, hostname)
The primary function for initiating a Kerberos security context on Windows.
This quickstart demonstrates how to initiate a Kerberos security context using `winkerberos.auth()`. This function leverages the underlying Windows SSPI to attempt authentication using the current user's Kerberos tickets. Success means a context object is returned, which can then be used for further token exchange in a client-server interaction.
import winkerberos
import os
# Example Service Principal Name (SPN) for a hypothetical service.
# In a real scenario, this would be a valid SPN for the service you want to authenticate with.
# For example: 'HTTP/webserver.example.com@EXAMPLE.COM'
SERVICE_PRINCIPAL = os.environ.get('WINKERBEROS_SPN', 'HTTP/localhost@EXAMPLE.COM')
HOSTNAME = os.environ.get('WINKERBEROS_HOSTNAME', 'localhost')
try:
# winkerberos typically uses the current logged-in user's credentials
# on a domain-joined Windows machine, so 'user'/'password' are often not needed.
context = winkerberos.auth(SERVICE_PRINCIPAL, HOSTNAME)
if context:
print(f"Successfully initiated Kerberos context for SPN: {SERVICE_PRINCIPAL}")
print("Kerberos authentication context established.")
# In a real application, 'context' would be used to generate tokens
# for further communication (e.g., context.step('challenge')).
else:
print(f"Failed to initiate Kerberos context for SPN: {SERVICE_PRINCIPAL}")
print("Ensure Kerberos is configured, tickets are available, and the SPN is valid.")
except winkerberos.GSSError as e:
print(f"Kerberos GSSAPI Error: {e}")
print("This often indicates issues with the Kerberos configuration, "
"network, or an invalid Service Principal Name (SPN).")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingUpgrading `winkerberos` may require a Python version upgrade. Version 0.11.0 dropped support for Python 3.7. Version 0.10.0 dropped support for Python 2.7, 3.5, and 3.6. Current versions (0.10.0+) require Python >=3.10.fixEnsure your Python environment meets the `winkerberos` version requirements. For newer `winkerberos` versions, upgrade Python to 3.10 or later. If unable to upgrade Python, pin `winkerberos` to an older compatible version (e.g., `<0.10.0` for Python 3.6, or `<0.11.0` for Python 3.7-3.9).
affects: 0.10.0 and newer
gotchaThis library is designed exclusively for Windows environments, leveraging the Security Support Provider Interface (SSPI). It will not function on Linux, macOS, or other operating systems.fixUse platform-agnostic Kerberos libraries like `python-kerberos` for cross-platform compatibility, or ensure deployment is strictly on Windows where `winkerberos` is needed.
affects: All versions
gotchaSuccessful authentication with `winkerberos` depends on a correctly configured Kerberos environment on the Windows host. This includes domain membership, access to a Key Distribution Center (KDC), valid service principal names (SPNs), and potentially existing Kerberos tickets.fixVerify the host machine's Kerberos configuration, network connectivity to the KDC, and ensure the target service has a correctly registered SPN. Use tools like `klist` to inspect current tickets and `setspn -L <machine_name>` to list SPNs.
affects: All versions
gotchaIncorrectly formatted or invalid Service Principal Names (SPNs) for `winkerberos.auth()` will result in `GSSError`s during context initiation.fixConfirm the exact SPN required by your target service (e.g., `service/host@REALM`) and ensure it's registered correctly in Active Directory or your KDC. Double-check case sensitivity and the realm part if explicitly provided.
affects: All versions
Upgrade
Version history
0.13.0latest on PyPI · released Dec 3, 2025
Audit
Dependencies
No dependency data recorded yet.