Install & Compatibility
Where this runs
tested against v2.0.57 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.432s · 26MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.6s · import 0.398s · 26MB
24MB installed
● package 24MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Zenpy
✓ from zenpy import Zenpy
Ticket
✓ from zenpy.lib.api_objects import Ticket
This quickstart demonstrates how to initialize the ZenPy client using API token authentication (recommended) and then create and retrieve a basic Zendesk ticket. Ensure `ZENDESK_EMAIL`, `ZENDESK_API_TOKEN`, and `ZENDESK_SUBDOMAIN` environment variables are set.
import os
from zenpy import Zenpy
from zenpy.lib.api_objects import Ticket
# Authenticate using environment variables (API Token is recommended)
creds = {
'email': os.environ.get('ZENDESK_EMAIL', 'your_email@example.com'),
'token': os.environ.get('ZENDESK_API_TOKEN', 'your_zendesk_api_token'),
'subdomain': os.environ.get('ZENDESK_SUBDOMAIN', 'your_subdomain')
}
# Create a Zenpy instance
try:
zenpy_client = Zenpy(**creds)
print("Successfully connected to Zendesk.")
# Create a new ticket
new_ticket = zenpy_client.tickets.create(
Ticket(
subject="Urgent: Coffee Machine Broken!",
description="The office coffee machine is completely out of order."
)
)
print(f"Created ticket with ID: {new_ticket.id}")
# Retrieve and print a ticket's subject
retrieved_ticket = zenpy_client.tickets(id=new_ticket.id)
print(f"Retrieved ticket subject: {retrieved_ticket.subject}")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingZendesk is deprecating password authentication for API calls. ZenPy version 2.0.53 introduced warnings (or errors, configurable via `password_treatment_level`) when using passwords. Relying solely on email and password will eventually break your integration.fixMigrate to Zendesk API tokens or OAuth for authentication. Update your `Zenpy` initialization to use `token` or `oauth_token` instead of `password`.
affects: >=2.0.53
breakingSupport for Python 3.5 was dropped in ZenPy version 2.0.49. Older Python environments using this version will experience compatibility issues.fixUpgrade your Python environment to Python 3.6 or newer.
affects: >=2.0.49
gotchaThe ZenPy Chat API now exclusively uses Zendesk API v2, deprecating direct reliance on the `zopim` endpoint that was previously used. This change was implemented in version 2.0.54.fixEnsure your Chat API interactions are compatible with Zendesk Chat API v2 endpoints and the updated ZenPy `zenpy_client.chats` methods, rather than direct `zopim` references.
affects: >=2.0.54
gotchaZendesk's bulk API operations typically have a limit (e.g., 100 objects per call). ZenPy does not automatically paginate or regulate this limit. Exceeding it can lead to `APIException` errors or silent truncation of your data by Zendesk.fixManually chunk your bulk operations to stay within Zendesk's documented limits (e.g., 100 objects per call) and handle `APIException` for robust error management.
affects: All 2.x versions
gotchaZenPy supports rate limiting controls but requires proper configuration to avoid HTTP 429 (Too Many Requests) errors. By default, it may sleep and retry, but this can cause long delays.fixConsider setting `raise_on_ratelimit=True` in the `Zenpy` constructor to handle `RateLimitError` exceptions programmatically, allowing you to implement custom retry logic (e.g., with backoff) or reschedule tasks. You can also configure `ratelimit_budget` or `proactive_ratelimit`.
affects: All 2.x versions
gotchaZenPy's pagination via Python slices has limitations. It always pulls the first 100 objects by default for certain endpoints and does not support negative slicing or multiple accesses of the same slice reliably.fixBe aware of the default 100-object fetch when using slices. For extensive pagination, refer to the documentation on 'Cursor Based Generators' or 'Incremental Exports' which may offer more robust solutions.
affects: All 2.x versions
Errors
Common errors & fixes
zenpy.lib.exception.APIException: 401 Client Error: Unauthorized for url:
The Zendesk subdomain, email, or API token provided during Zenpy client initialization is incorrect, incomplete, or lacks the necessary permissions for the requested action.
fixDouble-check the `subdomain`, `email`, and `token` when initializing Zenpy. Ensure the API token is active in Zendesk and has the required scopes.
zenpy.lib.exception.APIException: 422 Client Error: Unprocessable Entity for url:
An attempt was made to create or update a Zendesk resource (e.g., a ticket, user) with invalid data, missing required fields, or data that violates Zendesk's API validation rules.
fixReview the data being sent to Zendesk. Ensure all mandatory fields are present and that field values adhere to Zendesk's data type and format requirements; the error details in the exception often provide specific validation failures.
zenpy.lib.exception.APIException: 404 Client Error: Not Found for url:
The requested Zendesk resource (e.g., a ticket, user, or organization) could not be found with the provided ID, or the authenticated user does not have permission to access it.
fixVerify that the ID of the resource you are trying to retrieve or modify is correct and actually exists in your Zendesk instance, and confirm the API token has the necessary permissions.
ModuleNotFoundError: No module named 'zenpy'
The `zenpy` library has not been installed in the current Python environment or the environment where the script is being executed.
fixInstall the library using pip: `pip install zenpy`. If using a virtual environment, ensure it is activated before running the installation command.
Upgrade
Version history
2.0.57latest on PyPI · released Feb 19, 2026
Audit
Dependencies
No dependency data recorded yet.