Install & Compatibility
Where this runs
tested against v? · pip install
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
dependency_conflict
glibcpy 3.10–3.95 runs
dependency_conflict
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Auto-instrumentation via opentelemetry-instrument
✓ opentelemetry-instrument python my_app.py
The `opentelemetry-distro` package is primarily used via the `opentelemetry-instrument` command-line wrapper, which applies auto-instrumentation at runtime based on discovered libraries and the distro's configuration.
To quickly get started, install `opentelemetry-distro[otlp]` and then run `opentelemetry-bootstrap -a install` to automatically install instrumentations for detected libraries. Then, run your application using the `opentelemetry-instrument` wrapper script. This example demonstrates a simple Flask application that makes an HTTP request, which will be automatically traced. Ensure an OpenTelemetry Collector is running to receive telemetry data. For Flask/Django, set `use_reloader=False` (Flask) or use `--noreload` (Django) to avoid instrumentation issues.
import os
import requests
from flask import Flask
app = Flask(__name__)
@app.route("/hello")
def hello_world():
return "Hello, World!"
@app.route("/external")
def call_external():
# This call should be traced automatically if requests is instrumented
response = requests.get("http://localhost:5001/hello")
return f"Called external service: {response.text}"
if __name__ == '__main__':
# Run this app with: opentelemetry-instrument python app.py
# Ensure an OpenTelemetry Collector is running on localhost:4317 or configure OTEL_EXPORTER_OTLP_ENDPOINT
# (e.g., docker run -p 4317:4317 -p 4318:4318 otel/opentelemetry-collector:latest --config=/etc/otel-collector-config.yaml)
# The collector config should include otlp receiver and a logging/debug exporter.
app.run(port=5001, debug=False, use_reloader=False)
opentelemetry-bootstrap --version
Debug
Known issues
gotchaOpenTelemetry Python, including `opentelemetry-distro`, is largely in beta. While tracing APIs are relatively stable, metrics and logging APIs are still evolving. This means breaking changes can occur between minor versions.fixReview release notes carefully before upgrading. Test new versions thoroughly in non-production environments.
affects: 0.x.x (all beta versions)
gotchaThe `opentelemetry-distro` configures a default OTLP SpanExporter, which attempts to send data to an OpenTelemetry Collector (by default on `http://localhost:4317` or `grpc://localhost:4317`). If no Collector is running or accessible, telemetry will not be exported.fixEnsure an OpenTelemetry Collector is running and accessible from your application. Configure the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable if your Collector is at a different address or port.
affects: All versions
breakingWhen using web frameworks like Flask or Django, running in debug mode with an enabled reloader (e.g., `app.run(debug=True)`) can conflict with auto-instrumentation, causing it to fail.fixDisable the reloader when using auto-instrumentation. For Flask, set `use_reloader=False` (e.g., `app.run(debug=True, use_reloader=False)`). For Django, use the `--noreload` flag when starting your application.
affects: All versions
gotchaThe generic `opentelemetry-distro` provides default configurations. If you intend to use a vendor-specific OpenTelemetry distribution (e.g., AWS Distro for OpenTelemetry, Azure Monitor OpenTelemetry Distro), ensure you install and use *that specific distro* as it often includes tailored exporters, resource detectors, and instrumentations for the target backend. Mixing distros or expecting generic distro to have vendor-specific features is a common mistake.fixIdentify your target observability backend and consult its specific OpenTelemetry documentation. Install the appropriate vendor-specific distro if one exists and is recommended.
affects: All versions
breakingThe `opentelemetry-bootstrap` command-line tool, often used for auto-instrumentation, may not support all common CLI arguments (e.g., `-q` for quiet mode). Passing unsupported arguments will result in an 'unrecognized arguments' error.fixEnsure `opentelemetry-bootstrap` is called with only its recognized arguments. If it's being implicitly called by a testing framework or script with flags like `-q`, modify the script to remove such flags when invoking `opentelemetry-bootstrap`.
affects: All versions
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
opentelemetry-apirequiredCore OpenTelemetry API, pulled in by the distro.
opentelemetry-sdkrequiredCore OpenTelemetry SDK, pulled in by the distro.
opentelemetry-instrumentationrequiredEnables auto-instrumentation capabilities, pulled in by the distro.
opentelemetry-exporter-otlpoptionalRequired for OTLP export, installed via the `[otlp]` extra.