Install & Compatibility
Where this runs
tested against v7.44.2 · 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.600s · 26.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.9s · import 0.554s · 27MB
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
posthoganalytics
✓ import posthoganalytics
✗ import posthog
The PyPI package name is `posthoganalytics`, not `posthog`. Using `import posthog` will likely lead to an `ImportError` or import a different, unrelated package.
Posthog
✓ from posthoganalytics import Posthog
Used to create an explicit client instance, especially recommended for web frameworks.
This quickstart demonstrates how to initialize the PostHog client, capture a custom event, and identify a user. It's crucial to call `posthoganalytics.flush()` in short-lived scripts to ensure events are sent before the program terminates. For long-running applications, `flush()` is handled automatically at intervals.
import os
import posthoganalytics
# Initialize PostHog client
posthoganalytics.init(
os.environ.get('POSTHOG_API_KEY', 'phc_YOUR_API_KEY'),
host=os.environ.get('POSTHOG_HOST', 'https://app.posthog.com')
)
# Capture an event
posthoganalytics.capture(
'test-user-id',
'my_event',
{'property_key': 'property_value'}
)
# Identify a user
posthoganalytics.identify(
'test-user-id',
{'email': 'test@example.com', 'name': 'Test User'}
)
# Ensure all events are sent before exiting
posthoganalytics.flush()
print('PostHog events captured and flushed.')
Debug
Known issues
gotchaFailing to call `posthoganalytics.flush()` or `posthoganalytics.shutdown()` in short-lived scripts or before your application exits can lead to lost events. Events are buffered and only sent periodically or upon explicit flush/shutdown.fixEnsure `posthoganalytics.flush()` is called before `sys.exit()` in scripts. For long-running applications, `posthoganalytics.shutdown()` can be used during graceful shutdown.
affects: All versions
gotchaIncorrect `POSTHOG_API_KEY` or `POSTHOG_HOST` configuration often leads to events being silently dropped, as the SDK will attempt to send data but fail to reach the correct PostHog instance.fixAlways verify your `POSTHOG_API_KEY` (project API key) and `POSTHOG_HOST` (e.g., `https://app.posthog.com` or your self-hosted instance URL). Check PostHog instance logs for incoming events or network traffic from your application.
affects: All versions
breakingIn versions 7.10.1 and earlier, the `capture_exceptions` argument in the Django middleware (if used) was implicitly passed as a positional argument. In 7.10.2+, it is strictly expected as a keyword argument.fixIf using PostHog's Django middleware and `capture_exceptions`, ensure it's passed as a keyword argument: `posthoganalytics.django.PosthogMiddleware(..., capture_exceptions=True)`.
affects: <=7.10.1 (Django users)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'posthoganalytics'
The `posthoganalytics` library has not been installed in the current Python environment.
fixpip install posthoganalytics
TypeError: distinct_id should be str or int
The `distinct_id` argument passed to `posthoganalytics.capture()`, `identify()`, or other methods, is neither a string nor an integer.
fixposthoganalytics.capture('user_id_string', 'event_name', {'prop': 'value'}) TypeError: __init__() missing 1 required positional argument: 'api_key'
The `Posthog` client class was instantiated without providing the mandatory `api_key` argument to its constructor.
fixfrom posthoganalytics import Posthog
posthog = Posthog('YOUR_API_KEY', host='https://app.posthog.com') AttributeError: module 'posthoganalytics' has no attribute 'init'
The `posthoganalytics` module does not have an `init()` method; initialization is done by setting module-level variables (`api_key`, `host`) or by instantiating the `Posthog` class.
fiximport posthoganalytics
posthoganalytics.api_key = 'YOUR_API_KEY'
posthoganalytics.host = 'https://app.posthog.com'
Upgrade
Version history
7.44.2latest on PyPI · released Aug 27, 2026
Audit
Dependencies
httpxrequiredUsed for HTTP requests to the PostHog API.
backoffrequiredUsed for retrying failed requests with exponential backoff.