posthog-django

This is a community package and is not an official PostHog-maintained library.

Django helpers for the PostHog Python SDK. This package provides a Django-ready client, middleware, feature flag helpers, and a small sugar API.

Install

pip install posthog-django

Configure

Add the app and middleware, then set your API keys.

# settings.py
INSTALLED_APPS = [
    # ...
    "posthog_django",
]

MIDDLEWARE = [
    # ...
    "posthog_django.middleware.PosthogContextMiddleware",
]

POSTHOG_PROJECT_API_KEY = "phc_your_project_key"
POSTHOG_PERSONAL_API_KEY = "phx_your_personal_key"  # required for local flag eval
POSTHOG_HOST = "https://app.posthog.com"  # optional

Capture events

from posthog_django import capture

def signup_view(request):
    # ...
    capture("user_signed_up", request=request, properties={"plan": "pro"})

Feature flags

from posthog_django import feature_enabled, get_feature_flag

def dashboard(request):
    if feature_enabled("new-dashboard", request=request):
        ...

    variant = get_feature_flag("pricing-experiment", request=request)

Settings reference

• POSTHOG_PROJECT_API_KEY or POSTHOG_API_KEY: required.
• POSTHOG_PERSONAL_API_KEY: required for local feature flag evaluation.
• POSTHOG_ENABLE_FEATURE_FLAGS: enable feature flag helpers and SDK local evaluation support (default: True). Set to False when feature flags are not used.
• POSTHOG_ENABLE_LOCAL_EVALUATION: poll and evaluate feature flags locally (default: True when POSTHOG_PERSONAL_API_KEY is configured; otherwise it is automatically disabled). This does not disable remote feature flag evaluation; use POSTHOG_ENABLE_FEATURE_FLAGS=False to disable the posthog_django feature flag helpers and SDK local evaluation.
• POSTHOG_HOST: PostHog host (default https://app.posthog.com).
• POSTHOG_ENABLED: enable/disable integration (default: enabled if API key is set).
• POSTHOG_DEBUG: enable SDK debug logging.
• POSTHOG_DISABLE_GEOIP: disable GeoIP lookup (default: True).
• POSTHOG_ERROR_MODE: log, raise, or ignore for SDK errors (default: log).
• POSTHOG_ENABLE_EXCEPTION_AUTOCAPTURE: enable exception autocapture.
• POSTHOG_CAPTURE_EXCEPTION_CODE_VARIABLES: capture code variables for exceptions.
• POSTHOG_CODE_VARIABLES_MASK_PATTERNS: list of regex patterns to mask.
• POSTHOG_CODE_VARIABLES_IGNORE_PATTERNS: list of regex patterns to ignore.
• POSTHOG_IN_APP_MODULES: list of module prefixes for in-app frames.
• POSTHOG_MW_CAPTURE_EXCEPTIONS: capture exceptions in middleware (default: True).
• POSTHOG_MW_CAPTURE_VIEWS: capture an event after each completed response (default: False).
• POSTHOG_MW_VIEW_EVENT_NAME: event name used for middleware view capture (default: $pageview).
• POSTHOG_MW_EXTRA_TAGS: callable returning extra context tags.
• POSTHOG_MW_REQUEST_FILTER: callable returning False to skip tracking.
• POSTHOG_MW_TAG_MAP: callable to mutate tags before they are added.
• POSTHOG_CACHE_ALIAS: Django cache alias to use (default: "default").
• POSTHOG_FLAG_DEFINITIONS_CACHE_TTL: seconds to cache flag definitions.
• POSTHOG_FLAG_DEFINITIONS_LOCK_TTL: seconds for the flag definition lock.
• POSTHOG_FLAG_DEFINITIONS_CACHE_PREFIX: cache key prefix for flag definitions.
• POSTHOG_FEATURE_FLAGS_CACHE_TTL: seconds to cache feature flag results.
• POSTHOG_FEATURE_FLAGS_CACHE_PREFIX: cache key prefix for feature flag results.
• POSTHOG_VALIDATE_ON_STARTUP: validate configuration on app startup.
• POSTHOG_VALIDATE_EVENT_NAME: event used for validation.
• POSTHOG_VALIDATE_DISTINCT_ID: distinct ID used for validation.

Exception code variables

Enable code variable capture globally:

# settings.py
POSTHOG_ENABLE_EXCEPTION_AUTOCAPTURE = True
POSTHOG_CAPTURE_EXCEPTION_CODE_VARIABLES = True

Override capture in specific blocks:

from posthog import new_context
from posthog_django import (
    set_capture_exception_code_variables_context,
    set_code_variables_mask_patterns_context,
    set_code_variables_ignore_patterns_context,
)

with new_context():
    set_capture_exception_code_variables_context(True)
    set_code_variables_mask_patterns_context([r".*password.*"])
    set_code_variables_ignore_patterns_context([r"^__.*"])
    do_sensitive_work()

Notes

• POSTHOG_ENABLE_FEATURE_FLAGS=False does not modify the raw PostHog SDK client returned by get_client(), posthog.client(), or exposed as request.posthog. Calls made directly on that client bypass the posthog_django feature flag helpers and their settings.
• Feature flag definition caching uses the configured Django cache backend and is enabled by default when a cache is available.
• Result caching for feature flags is opt-in by setting POSTHOG_FEATURE_FLAGS_CACHE_TTL. To preserve $feature_flag_called events, keep send_feature_flag_events=True (cache is skipped in that case).

Example project

See example/ for a minimal Django project that wires in the middleware and shows event capture + feature flags.