{"id":4687,"library":"posthoganalytics","title":"PostHog Python SDK","description":"The official Python SDK for PostHog, enabling integration into any Python application for product analytics, feature flags, and session recording. It's actively maintained with frequent minor releases, often addressing specific framework integrations or new AI/LLM-related tracking features.","status":"active","version":"7.11.0","language":"en","source_language":"en","source_url":"https://github.com/posthog/posthog-python","tags":["analytics","product analytics","telemetry","feature flags","a/b testing","marketing","observability"],"install":[{"cmd":"pip install posthoganalytics","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for HTTP requests to the PostHog API.","package":"httpx","optional":false},{"reason":"Used for retrying failed requests with exponential backoff.","package":"backoff","optional":false}],"imports":[{"note":"The PyPI package name is `posthoganalytics`, not `posthog`. Using `import posthog` will likely lead to an `ImportError` or import a different, unrelated package.","wrong":"import posthog","symbol":"posthoganalytics","correct":"import posthoganalytics"},{"note":"Used to create an explicit client instance, especially recommended for web frameworks.","symbol":"Posthog","correct":"from posthoganalytics import Posthog"}],"quickstart":{"code":"import os\nimport posthoganalytics\n\n# Initialize PostHog client\nposthoganalytics.init(\n    os.environ.get('POSTHOG_API_KEY', 'phc_YOUR_API_KEY'),\n    host=os.environ.get('POSTHOG_HOST', 'https://app.posthog.com')\n)\n\n# Capture an event\nposthoganalytics.capture(\n    'test-user-id',\n    'my_event', \n    {'property_key': 'property_value'}\n)\n\n# Identify a user\nposthoganalytics.identify(\n    'test-user-id',\n    {'email': 'test@example.com', 'name': 'Test User'}\n)\n\n# Ensure all events are sent before exiting\nposthoganalytics.flush()\nprint('PostHog events captured and flushed.')\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure `posthoganalytics.flush()` is called before `sys.exit()` in scripts. For long-running applications, `posthoganalytics.shutdown()` can be used during graceful shutdown.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If using PostHog's Django middleware and `capture_exceptions`, ensure it's passed as a keyword argument: `posthoganalytics.django.PosthogMiddleware(..., capture_exceptions=True)`.","message":"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.","severity":"breaking","affected_versions":"<=7.10.1 (Django users)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}