Install & Compatibility
Where this runs
tested against v7.0.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.95 runs
installs and imports cleanly · install 0.0s · import 0.276s · 22.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.4s · import 0.262s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RestApiV2Client
✓ from pagerduty import RestApiV2Client
✗ from pdpyras import APISession
The `pdpyras` module and its classes like `APISession` are deprecated. `pagerduty` is the new module, and `RestApiV2Client` is its equivalent.
EventsApiV2Client
✓ from pagerduty import EventsApiV2Client
✗ from pdpyras import EventsAPISession
The `pdpyras` module and its classes like `EventsAPISession` are deprecated. `pagerduty` is the new module, and `EventsApiV2Client` is its equivalent.
This quickstart demonstrates how to initialize the PagerDuty `RestApiV2Client` and perform a basic API call, such as listing users. It highlights the importance of setting the `PAGERDUTY_API_KEY` and, for account-level API keys, the `PAGERDUTY_FROM_EMAIL` header for certain write operations.
import os
from pagerduty import RestApiV2Client
# PagerDuty API Key (recommended: user-scoped or service-specific key)
PAGERDUTY_API_KEY = os.environ.get('PAGERDUTY_API_KEY', 'YOUR_PAGERDUTY_API_KEY')
# 'From' email header is required for some actions (e.g., resolving incidents)
# when using an account-level API key.
PAGERDUTY_FROM_EMAIL = os.environ.get('PAGERDUTY_FROM_EMAIL', 'your_user@example.com')
if not PAGERDUTY_API_KEY or PAGERDUTY_API_KEY == 'YOUR_PAGERDUTY_API_KEY':
print("Error: PAGERDUTY_API_KEY environment variable not set or placeholder used.")
exit(1)
try:
# Initialize the REST API client
# For account-level API keys, pass default_from for actions requiring a 'From' header
client = RestApiV2Client(PAGERDUTY_API_KEY, default_from=PAGERDUTY_FROM_EMAIL)
# Example: List users
print("Fetching PagerDuty users...")
users_response = client.get('/users')
if users_response.is_success:
users = users_response.json().get('users', [])
for user in users:
print(f"User ID: {user['id']}, Name: {user['name']}, Email: {user['email']}")
print(f"Successfully fetched {len(users)} users.")
else:
print(f"Error fetching users: {users_response.status_code} - {users_response.text}")
# Example: Create an incident (requires a service API key, not account-level)
# This example requires a valid `service_id` and `from` email and a user with permissions
# incident_data = {
# "incident": {
# "type": "incident",
# "title": "Test Incident from Python Client",
# "service": {"id": "PXXXXXX", "type": "service_reference"},
# "priority": {"id": "PXXXXXX", "type": "priority_reference"}, # Optional
# "body": {"type": "text", "details": "This is a test incident created via the Python client."}
# }
# }
# create_incident_response = client.post('/incidents', json=incident_data, headers={'From': PAGERDUTY_FROM_EMAIL})
# if create_incident_response.is_success:
# print(f"Incident created: {create_incident_response.json()['incident']['id']}")
# else:
# print(f"Error creating incident: {create_incident_response.status_code} - {create_incident_response.text}")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingThe `pdpyras` library has been deprecated and replaced by `python-pagerduty` (installed as `pagerduty`). This involves a module rename (e.g., `import pdpyras` becomes `import pagerduty`) and significant class renames (e.g., `pdpyras.APISession` is now `pagerduty.RestApiV2Client`, `pdpyras.EventsAPISession` is now `pagerduty.EventsApiV2Client`). Projects should migrate to the new library and its updated class names.fixUpdate imports from `pdpyras` to `pagerduty` and refactor client class instantiations according to the `PDPYRAS Migration Guide` in the `python-pagerduty` documentation. For example, change `session = pdpyras.APISession(API_KEY)` to `client = pagerduty.RestApiV2Client(API_KEY)`.
affects: <= v0.x (pdpyras), all `pagerduty` versions migrating from `pdpyras`
breakingVersion 6.0.0 switched the underlying HTTP client from `requests` to `httpx`. While the developer interface is largely similar, this change introduces breaking changes, particularly in how the client is configured to use a proxy server.fixReview any code that directly interacted with the underlying `requests` session or configured proxy settings. Refer to the `httpx` documentation for equivalent configurations.
affects: >= 6.0.0
gotchaWhen using an account-level PagerDuty API key (created by an administrator), certain API actions, especially those that take action on incidents (e.g., acknowledge, resolve), require a `From` header. This header's value must be the email address of a valid PagerDuty user, otherwise, requests may result in an HTTP 400 error.fixPass the `default_from` keyword argument during client instantiation (e.g., `client = RestApiV2Client(API_KEY, default_from='user@example.com')`) or set it via `client.default_from = 'user@example.com'`.
affects: All versions
gotchaFor PagerDuty accounts located in the EU service region, the API URL might need to be explicitly configured. While v6.2.0 introduced improvements for supporting EU regions, older versions or specific configurations might still require setting the `api_url` parameter during client initialization to the appropriate EU endpoint (e.g., `https://api.eu.pagerduty.com`).fixIf encountering connectivity issues or incorrect data for EU accounts, ensure the `api_url` parameter is set correctly during `RestApiV2Client` or `EventsApiV2Client` initialization. The library may handle this automatically in recent versions, but explicit setting can resolve issues.
affects: <= 6.1.0, potentially some >= 6.2.0 configurations
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pagerduty'
The `pagerduty` package is not installed in the Python environment being used.
fixInstall the library using pip: `pip install pagerduty`
pagerduty.HttpError: HTTP 4XX Client Error: (e.g., 400 Bad Request, 401 Unauthorized)
This error typically indicates issues with authentication (invalid API key or OAuth token), insufficient permissions for the action, or a missing/incorrect 'From' header for certain REST API v2 endpoints (like creating or updating incidents) when using an account-level API key.
fixEnsure your `API_KEY` or OAuth token is valid and has the necessary permissions. For REST API v2 calls that modify resources (e.g., incidents), provide a `default_from` email address when initializing the client or set a `From` header in your request, specifying a valid PagerDuty user's email: `client = pagerduty.RestApiV2Client(API_KEY, default_from="user@example.com")`.
KeyError: 'some_missing_key'
This occurs when attempting to access a key in a dictionary (typically an API response payload) that does not exist, often due to an unexpected API response structure or incorrect assumptions about the data returned by the PagerDuty API.
fixSafely access dictionary keys using the `.get()` method with a default value, or check for key existence using the `in` operator before access. Review PagerDuty API documentation for the expected response structure for the specific endpoint you are calling.
AttributeError: 'NoneType' object has no attribute 'something' (or similar on client/response objects)
This error arises when you try to access an attribute or method on an object that is `None` or an unexpected type. This can happen if an API call failed and returned `None` instead of a client object or a response, or if you are trying to use a method/attribute from an older version of the library (e.g., `pdpyras`) on the current `pagerduty` client.
fixAlways check if the object is `None` before attempting to access its attributes or methods. Verify that the methods and attributes you are using are correct for the `pagerduty` library (version 6.2.1) and that your API calls are successfully returning the expected objects.
Upgrade
Version history
7.0.0latest on PyPI · released Jul 15, 2026
Audit
Dependencies
httpxrequiredThe library uses httpx as its underlying HTTP client since v6.0.0.