Install & Compatibility
Where this runs
tested against v5.15.1 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.553s · 47MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.1s · import 0.499s · 47MB
46MB installed
● package 46MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
EventHubProducerClient
✓ from azure.eventhub import EventHubProducerClient
EventHubConsumerClient
✓ from azure.eventhub import EventHubConsumerClient
EventData
✓ from azure.eventhub import EventData
EventProcessorClient
✓ from azure.eventhub import EventProcessorClient
EventHubClient
✓ from azure.eventhub import EventHubProducerClient, EventHubConsumerClient
✗ from azure.eventhub import EventHubClient
The `EventHubClient` class from previous 'Track 1' SDKs (v1-v4) was removed in v5.0.0. Use `EventHubProducerClient` for sending and `EventHubConsumerClient` for basic receiving, or `EventProcessorClient` for distributed processing with checkpointing.
This quickstart demonstrates how to send a batch of events to an Azure Event Hub using the `EventHubProducerClient`. It uses environment variables for secure credential management and showcases the async API pattern, which is standard for the Track 2 Azure SDKs.
import os
import asyncio
from azure.eventhub import EventHubProducerClient, EventData
# Retrieve connection string and Event Hub name from environment variables.
# For local development, replace 'os.environ.get(...)' with your actual values.
# Connection string for Event Hubs Namespace, NOT a specific Event Hub.
CONNECTION_STR = os.environ.get("EVENT_HUB_CONNECTION_STR", "Endpoint=sb://<NAMESPACE>.servicebus.windows.net/;SharedAccessKeyName=<KEY_NAME>;SharedAccessKey=<KEY>")
# The specific Event Hub name within the namespace
EVENTHUB_NAME = os.environ.get("EVENT_HUB_NAME", "<YOUR_EVENT_HUB_NAME>")
async def send_events():
producer = EventHubProducerClient.from_connection_string(
conn_str=CONNECTION_STR,
eventhub_name=EVENTHUB_NAME
)
async with producer:
event_data_batch = await producer.create_batch()
event_data_batch.add(EventData("Hello Azure Event Hubs!"))
event_data_batch.add(EventData("This is my second event."))
await producer.send_batch(event_data_batch)
print("Sent a batch of two events successfully.")
if __name__ == "__main__":
# Ensure you have set the EVENT_HUB_CONNECTION_STR and EVENT_HUB_NAME
# environment variables or replaced the placeholders.
if not CONNECTION_STR or '<NAMESPACE>' in CONNECTION_STR:
print("Please set the EVENT_HUB_CONNECTION_STR and EVENT_HUB_NAME environment variables.")
print("Example: export EVENT_HUB_CONNECTION_STR='Endpoint=sb://...;SharedAccessKeyName=...;SharedAccessKey=...'")
print("Example: export EVENT_HUB_NAME='myhub'")
else:
asyncio.run(send_events())
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'azure.eventhub'; 'azure' is not a package
This error typically occurs when there's a naming conflict in your Python environment, often a local file or directory named `azure.py` or `azure` that shadows the actual installed `azure` package, preventing the interpreter from finding the `azure.eventhub` submodule.
fixRename any local files or directories named `azure.py` or `azure` in your project or in paths that precede the site-packages directory in `sys.path`. Ensure `azure-eventhub` is correctly installed: `pip install azure-eventhub`.
azure.eventhub.exceptions.AuthenticationError: CBS Token authentication failed
This authentication error usually indicates that the connection string, Shared Access Signature (SAS) key, or Managed Identity configuration used to connect to Azure Event Hubs is incorrect, expired, or lacks the necessary permissions (Send, Receive, or Manage). Common issues include typos in the Event Hub name, using a namespace connection string instead of an Event Hub-specific one when `EntityPath` is missing, or clock skew.
fixVerify the connection string, including the `EntityPath` (Event Hub name), and ensure the SAS key is correct and current. For Managed Identity, confirm the correct Azure RBAC roles (e.g., 'Azure Event Hubs Data Sender' or 'Receiver') are assigned to your identity at the appropriate scope. Ensure your system clock is synchronized.
ImportError: cannot import name 'EventHubClient' from 'azure.eventhub'
This error occurs when attempting to import `EventHubClient`, `Sender`, or `Receiver` which are from older, deprecated versions of the `azure-eventhubs` SDK. The current `azure-eventhub` (Track 2) library uses different class names and an async-first API.
fixUpdate your import statements and code to use the modern Track 2 classes like `EventHubProducerClient` for sending and `EventHubConsumerClient` for receiving. For example, replace `from azure.eventhub import EventHubClient, Sender` with `from azure.eventhub import EventHubProducerClient`.
azure.eventhub.exceptions.EventHubError: ErrorCodes.ResourceLimitExceeded: Exceeded the maximum number of allowed receivers per partition in a consumer group which is 5.
This error indicates that you have exceeded the quota of active receivers for a single partition within a specific consumer group. Event Hubs typically limits a consumer group to 5 concurrent receivers per partition.
fixEnsure your application design reuses `EventHubConsumerClient` instances instead of creating new ones for each request. For multiple consumers, use different consumer groups, or ensure that the total number of active receivers per partition across all instances for a given consumer group does not exceed the limit.
At least one receiver for the endpoint is created with epoch of 'X', and so non-epoch receiver is not allowed. Either reconnect with a higher epoch, or make sure all epoch receivers are closed or disconnected.
This error happens when an 'epoch receiver' (typically used by `EventProcessorClient` for exclusive partition ownership) is active on a partition, preventing 'non-epoch receivers' (like simple `EventHubConsumerClient` instances without explicit `owner_level`) from connecting to the same partition and consumer group.
fixIdentify and stop any conflicting `EventProcessorClient` instances or other consumers using an epoch receiver on the same partition and consumer group. Alternatively, use a dedicated consumer group for your non-epoch receiver, or configure your receiver with an `owner_level` (epoch) higher than the one currently holding the lease to assert new ownership.
Upgrade
Version history
5.15.1latest on PyPI · released Oct 30, 2025
Audit
Dependencies
azure-corerequiredFundamental shared components for Azure SDKs (implicit dependency).
azure-eventhub-checkpointstorebloboptionalRequired for EventProcessorClient to store checkpoints in Azure Blob Storage. Other checkpoint stores exist but must be explicitly installed.