Install & Compatibility
Where this runs
tested against v3.13.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.060s · 43.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.054s · 41MB
39MB installed
● package 39MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from pulsar import Client
Producer
✓ from pulsar import Producer
Consumer
✓ from pulsar import Consumer
MessageId
✓ from pulsar import MessageId
Schema
✓ from pulsar import Schema
Used for structured message types like Avro or JSON schemas.
ConsumerType
✓ from pulsar import ConsumerType
Defines how messages are delivered to consumers within a subscription.
This quickstart demonstrates how to produce and consume messages using the `pulsar-client` library. It assumes a Pulsar broker is running and accessible (e.g., via `pulsar://localhost:6650`). The script first acts as a producer, sending three messages to a topic, then switches to a consumer, subscribing to the same topic and receiving those messages. Crucially, it shows proper resource management by calling `.close()` on clients, producers, and consumers. The Pulsar broker URL can be configured via the `PULSAR_BROKER_URL` environment variable.
import pulsar
import time
import os
# --- Configuration ---
# Ensure a Pulsar broker is running, e.g., locally via Docker:
# docker run -it -p 6650:6650 -p 8080:8080 apachepulsar/pulsar:latest bin/pulsar standalone
PULSAR_BROKER_URL = os.environ.get('PULSAR_BROKER_URL', 'pulsar://localhost:6650')
TOPIC_NAME = 'persistent://public/default/my-python-topic-qs'
SUBSCRIPTION_NAME = 'my-python-subscription-qs'
print(f"Connecting to Pulsar at: {PULSAR_BROKER_URL}")
# --- Producer ---
try:
print("\n--- Starting Producer ---")
client_producer = pulsar.Client(PULSAR_BROKER_URL)
producer = client_producer.create_producer(TOPIC_NAME)
for i in range(3):
message_data = f"hello-pulsar-message-{i}".encode('utf-8')
producer.send(message_data)
print(f"Producer sent: {message_data.decode()}")
time.sleep(0.1) # Small delay
producer.close()
client_producer.close()
print("--- Producer finished. ---")
except Exception as e:
print(f"Producer error: {e}")
time.sleep(1) # Give a moment for messages to be available in the topic
# --- Consumer ---
try:
print("\n--- Starting Consumer ---")
client_consumer = pulsar.Client(PULSAR_BROKER_URL)
consumer = client_consumer.subscribe(TOPIC_NAME, SUBSCRIPTION_NAME, consumer_type=pulsar.ConsumerType.Shared)
print("Consumer waiting for messages...")
received_count = 0
# We expect 3 messages from the producer
while received_count < 3:
try:
msg = consumer.receive(timeout_millis=3000) # Wait up to 3 seconds
if msg:
print(f"Consumer received: '{msg.data().decode('utf-8')}' (ID: {msg.message_id()})")
consumer.acknowledge(msg)
received_count += 1
else:
print("Consumer timed out waiting for message. Retrying...")
except Exception as msg_err:
print(f"Error receiving individual message: {msg_err}")
break # Exit on error
consumer.close()
client_consumer.close()
print("---
Consumer finished. ---")
except Exception as e:
print(f"Consumer error: {e}")
print("\nQuickstart demonstration complete.")
Debug
Known issues
breakingPulsar Python client versions are generally aligned with Apache Pulsar Broker versions. Using a client version (e.g., 3.x) with an older broker (e.g., 2.x) or vice-versa might lead to unexpected behavior, missing features, or connection failures. Always ensure compatibility between client and broker versions.fixRefer to the official Apache Pulsar documentation for the recommended client-broker compatibility matrix. Upgrade your client and/or broker to compatible versions.
affects: All versions, especially major version bumps (e.g., 2.x to 3.x)
gotchaFailing to explicitly call `.close()` on `pulsar.Client`, `Producer`, and `Consumer` objects can lead to resource leaks (e.g., open connections, file descriptors) and connection issues in long-running applications.fixAlways ensure `.close()` is called on these objects when they are no longer needed, typically in `finally` blocks or by using `with` statements if available (though not directly supported by current `pulsar-client` objects in a context manager way for `close()`).
affects: All versions
gotchaCorrectly configuring authentication (e.g., JWT tokens) and TLS for secure connections is a common source of initial setup errors. Incorrect parameters can lead to connection refused errors or authentication failures.fixCarefully review the documentation for `pulsar.Client` constructor parameters like `authentication`, `tls_enable`, `tls_trust_certs_file`, `tls_allow_insecure_connection`, etc. Ensure paths to certificate files are correct and tokens are valid. Set `tls_enable=True` for TLS connections.
affects: All versions
Errors
Common errors & fixes
ImportError: No module named '_pulsar'
The `pulsar-client` Python library is a C++ binding. This error occurs when the underlying C++ shared library (`_pulsar.so` or `.dylib`) cannot be found or loaded, often due to an incomplete installation, incompatible Python version, or missing runtime dependencies, especially on macOS.
fixEnsure `pulsar-client` is correctly installed for your specific Python version and operating system. It's recommended to use a virtual environment and ensure Python 3.7 or later is used. Reinstall using `pip install pulsar-client` or `python -m pip install pulsar-client`.
Exception: Pulsar error: IncompatibleSchema
This error arises when a producer or consumer attempts to interact with a Pulsar topic, but the schema defined in the client code is incompatible with the schema already established on that topic, or if there are issues with Avro/JSON schema definitions or their required dependencies.
fixVerify that the schema specified in your `pulsar.Client.create_producer` or `client.subscribe` call (e.g., `schema=AvroSchema(...)` or `schema=JsonSchema(...)`) precisely matches the topic's existing schema. If using Avro, ensure `pulsar-client[avro]` is installed (`pip install 'pulsar-client[avro]'`) and your Avro schema definition is valid.
_pulsar.ConnectError: Pulsar error: ConnectError
This connection error, often accompanied by logs like 'Failed to establish connection: Connection refused', indicates that the Python client could not establish a connection with the Pulsar broker. This can be due to an incorrect `service_url`, the broker not running, network issues (e.g., firewall blocking access, unreachable host), or a failure in the authentication process.
fixConfirm that the Pulsar broker is running and is network-accessible from where your client code is executing. Double-check the `service_url` string (e.g., `pulsar://localhost:6650` or `pulsar+ssl://broker.example.com:6651`) and ensure any necessary authentication parameters (e.g., tokens, TLS certificates) are correctly configured and valid.
AttributeError: module 'pulsar' has no attribute 'Client'
This error typically occurs if the `pulsar` module is imported but the `Client` class is not directly accessible under `pulsar.Client`. Common reasons include a local file named `pulsar.py` shadowing the installed library, an incorrect import statement, or an attempt to use the `Client` class before the module is properly loaded or after it has been potentially corrupted.
fixEnsure there is no conflicting local Python file named `pulsar.py` in your project directory or Python path that could be imported instead of the actual `pulsar-client` library. The standard and correct way to import and instantiate the client is `import pulsar` followed by `client = pulsar.Client('pulsar://...')`. Upgrade
Version history
3.13.0latest on PyPI · released Jul 2, 2026
Audit
Dependencies
No dependency data recorded yet.