---
id: py-zipkin
version: "1.2.8"
license: Copyright Yelp 2019
license_treatment: permissive
maintenance: active
---

# py-zipkin — Library for using Zipkin in Python.

License: permissive · Maintenance: active · Downloads: 484.2K/mo

## What it is and what it does

py_zipkin is a Python library that integrates Zipkin distributed tracing into your applications. It provides the zipkin_span context manager and decorator to wrap code blocks or functions, automatically creating and sending trace spans to a Zipkin collector. The library handles span creation, sampling, and context propagation across service boundaries.

You supply a transport handler (HTTP, Kafka, or custom) that encodes spans in thrift format and sends them to your Zipkin backend. py_zipkin manages the trace context using thread-local storage by default, with support for explicit Stack and SpanStorage instances in multithreaded or async environments. It also offers utilities to add binary annotations, mark remote service calls, and generate HTTP headers for propagating trace context to downstream services.

Use it for:

- Instrument a microservice to trace requests end-to-end across multiple services by propagating trace headers.
- Add sampling-based tracing to high-throughput services to monitor latency and service dependencies without capturing every request.
- Record custom span metadata (binary annotations) during request processing to track business logic or debug information.
- Mark calls to non-instrumented external services with remote endpoint annotations so the trace graph shows the full call chain.
- Implement firehose mode to capture 100% of spans for a subset of traffic and route them to a separate retention backend.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

py_zipkin provides context managers and decorators to instrument Python applications with Zipkin distributed tracing, sending span data to a central collector via pluggable transport handlers.

Yes, if you are already running Zipkin and need Python instrumentation. The library is actively maintained, has low install friction, and provides a clean API for both simple and complex tracing scenarios. The Apache v2 license poses no restrictions. Consider it essential for microservice observability in a Zipkin-based infrastructure; not relevant if you use a different tracing backend (Jaeger, DataDog, etc.).

## Install

pip install py-zipkin
uv add py-zipkin
poetry add py-zipkin

## Installing py-zipkin

Before you install: Low install friction with a single runtime dependency (typing-extensions). Maintenance status is active with recent commits as of 2026-04-02, though the latest release was 2023-03-24.

License in practice: Licensed under Apache v2 (permissive). No restrictions on commercial or private use; modifications and redistribution are allowed under Apache terms.

Quickstart:

pip install py_zipkin

from py_zipkin.zipkin import zipkin_span
from py_zipkin.transport import BaseTransportHandler

class MyTransport(BaseTransportHandler):
    def get_max_payload_bytes(self):
        return None
    def send(self, encoded_span):
        pass  # Send to Zipkin collector

with zipkin_span(
    service_name='my_service',
    span_name='my_operation',
    transport_handler=MyTransport(),
    port=9411,
    sample_rate=0.05,
):
    # Your code here
    pass

Requires a transport handler implementation to send spans; without one, spans are created but not exported. Zipkin collector endpoint must be accessible from your application.

Verify before relying:

- Whether the package supports async/await patterns beyond the experimental multithreading guidance in the documentation.
- Current compatibility with Python versions beyond 3.7 and 3.8 (classifiers list only those two, but requires_python states >=3.7).
- Whether firehose mode overhead is acceptable for production workloads at scale.

## Package facts

- License: Copyright Yelp 2019 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 484.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

zipkin tracing python, distributed tracing instrumentation, span context manager decorator, service call tracing, trace sampling and collection, distributed-tracing, observability, zipkin

[View on SkillFed](https://skillfed.io/packages/py-zipkin) · [View on PyPI](https://pypi.org/project/py-zipkin/)