PostHog Python SDK

Warnings

• gotcha Failing 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.
  Fix: Ensure `posthoganalytics.flush()` is called before `sys.exit()` in scripts. For long-running applications, `posthoganalytics.shutdown()` can be used during graceful shutdown.
• gotcha Incorrect `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.
  Fix: Always 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.
• breaking In 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.
  Fix: If using PostHog's Django middleware and `capture_exceptions`, ensure it's passed as a keyword argument: `posthoganalytics.django.PosthogMiddleware(..., capture_exceptions=True)`.

Install

• pip install posthoganalytics Install latest version

Imports

• posthoganalytics

  import posthoganalytics

  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.

Quickstart

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.')