PostHog Python SDK

Warnings

• breaking Version 6.x introduced breaking changes, most notably deprecating the global `posthog.identify()` method in favor of a new `contexts` API. The `capture()` method signature also changed, requiring keyword arguments instead of positional ones for `distinct_id`.
  Fix: Migrate from `identify()` to `identify_context()` within a `new_context()` block. Update all `capture()` and `capture_exception()` calls to use keyword arguments for parameters like `distinct_id` and `event`.
• breaking PostHog Python SDK versions 7.x.x and higher no longer support Python 3.9. Projects using Python 3.9 will need to upgrade their Python version to 3.10 or newer to use the latest SDK versions.
  Fix: Upgrade your Python environment to 3.10 or higher before upgrading to PostHog SDK version 7.0.0+.
• gotcha In serverless environments (e.g., AWS Lambda, Google Cloud Functions), buffered events might be lost if the function terminates before the PostHog client can flush its queue. By default, events are sent on background threads.
  Fix: Ensure `posthog.shutdown()` is explicitly called before the function exits, or initialize the client with `sync_mode=True` (e.g., `posthog = Posthog(..., sync_mode=True)`) to send events synchronously.
• gotcha The primary `posthog` client is designed with background threads for non-blocking `capture()` calls, but it is not inherently `async/await` compatible. Developers expecting full `asyncio` integration might find this limiting.
  Fix: For true asynchronous use cases, consider existing asynchronous forks (e.g., `posthog-async` - note this is a separate package) or specific async integrations provided by PostHog (e.g., for LLM clients). The core client's `capture()` is non-blocking but not `awaitable`.
• gotcha PostHog JavaScript snippets can be blocked by ad blockers in browsers, potentially leading to incomplete data. While this is a frontend concern, it can impact the comprehensiveness of analytics data if not addressed.
  Fix: For production environments, consider setting up a reverse proxy to circumvent ad blockers and ensure more reliable data ingestion.
• gotcha Hardcoding your PostHog `project_api_key` and `host` directly in your application code is a security risk, especially for production deployments.
  Fix: Always use environment variables (e.g., `os.environ.get('POSTHOG_PROJECT_API_KEY')`) to securely pass your API key and host to the PostHog client upon initialization.

Install

• pip install posthog Install PostHog Python SDK

Imports

• Posthog

  from posthog import Posthog

  Initializes the main PostHog client.
• capture

  posthog.capture(...)

  Called on an initialized Posthog client instance.
• identify_context

  from posthog import identify_context

  Used with contexts for user identification, especially in server-side applications.
• new_context

  from posthog import new_context

  Used to create a new scope for managing shared state across capture calls.

Quickstart

This quickstart demonstrates how to initialize the PostHog client with environment variables, capture a custom event, and evaluate a feature flag. It also includes an important step for graceful shutdown to ensure all buffered events are sent.

import os
from posthog import Posthog

# Initialize PostHog client using environment variables for API key and host
# Replace 'your_project_api_key' and 'https://us.i.posthog.com' with your actual values
# or ensure POSTHOG_PROJECT_API_KEY and POSTHOG_HOST are set in your environment.
posthog = Posthog(
    project_api_key=os.environ.get('POSTHOG_PROJECT_API_KEY', 'your_project_api_key'),
    host=os.environ.get('POSTHOG_HOST', 'https://us.i.posthog.com')
)

# Capture a custom event
distinct_id = "user_123_unique_id" # A unique identifier for the user or entity

posthog.capture(
    distinct_id=distinct_id,
    event="user_signed_up",
    properties={
        "plan": "free",
        "signup_method": "email_password"
    }
)

# Evaluate a feature flag
is_new_feature_enabled = posthog.feature_enabled(
    'new-feature-flag-key',
    distinct_id # Feature flags usually require a distinct_id
)

if is_new_feature_enabled:
    print(f"New feature is enabled for {distinct_id}!")
else:
    print(f"New feature is NOT enabled for {distinct_id}.")

# In serverless environments or scripts, ensure events are flushed before exiting.
# For long-running applications (e.g., web servers), this is often handled automatically
# by background threads, but explicit shutdown is good practice for reliability.
posthog.shutdown()
print("PostHog client shut down and events flushed.")