Integration Django

PostHogOfficialCreated by PostHog

Skill
Tool integration
Data and AI
MIT
Low risk

Download ZIP

From the author

PostHog integration for Django applications

— the description by PostHog

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a systematic approach to implementing PostHog analytics within a Django project. It covers the installation of the Python SDK, configuration of middleware for automatic context extraction, and best practices for server-side event tracking and user identification. The skill emphasizes maintaining clean code by using environment variables, leveraging the built-in PosthogContextMiddleware, and following established patterns for capturing events and exceptions without exposing PII.

What it does

Guides the installation of the PostHog Python SDK.
Configures Django middleware for automatic session and user context tracking.
Provides patterns for server-side event capture and user identification.
Ensures secure handling of API keys via environment variables.
Facilitates automatic exception tracking for improved error visibility.
Standardizes event property usage to protect user privacy.

When to use it

When adding product analytics to a new or existing Django application.
When you need to track server-side business logic, such as payment processing or authentication.
When implementing automated error tracking and reporting in a Django environment.
When you need to correlate frontend and backend user sessions.

Advantages

Reduces boilerplate by using built-in middleware for context extraction.
Promotes secure practices by mandating environment variables for configuration.
Ensures consistent event tracking patterns across the application.
Provides clear separation between PII (identify) and metadata (capture).

Usage examples

“How do I initialize PostHog in my Django project?”: The skill instructs you to add the PosthogContextMiddleware to your settings and initialize the Posthog client within your AppConfig.ready() method using environment variables.
“How should I track a user login event?”: Use the posthog.new_context() pattern to identify the user with identify_context() and then call posthog.capture() to record the login event with relevant properties.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/posthog/integration-django/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip integration-django.zip -d .agents/skills

Documentation by PostHog

PostHog integration for Django

This skill helps you add PostHog analytics to Django applications.

Workflow

Follow these steps in order to complete the integration:

basic-integration-1.0-begin.md - PostHog Setup - Begin ← Start here
basic-integration-1.1-edit.md - PostHog Setup - Edit
basic-integration-1.2-revise.md - PostHog Setup - Revise
basic-integration-1.3-conclude.md - PostHog Setup - Conclusion

Reference files

references/EXAMPLE.md - Django example project code
references/django.md - Django - docs
references/identify-users.md - Identify users - docs
references/basic-integration-1.0-begin.md - PostHog setup - begin
references/basic-integration-1.1-edit.md - PostHog setup - edit
references/basic-integration-1.2-revise.md - PostHog setup - revise
references/basic-integration-1.3-conclude.md - PostHog setup - conclusion

The example project shows the target implementation pattern. Consult the documentation for API details.

Key principles

Environment variables: Always use environment variables for PostHog keys. Never hardcode them.
Minimal changes: Add PostHog code alongside existing integrations. Don't replace or restructure existing code.
Match the example: Your implementation should follow the example project's patterns as closely as possible.

Framework guidelines

Add 'posthog.integrations.django.PosthogContextMiddleware' to MIDDLEWARE it auto-extracts tracing headers and captures exceptions
Initialize PostHog in AppConfig.ready() with api_key and host from environment variables
Use the context API pattern with new_context(), identify_context(user_id), then capture()
For login/logout views, create a new context since user state changes during the request
Do NOT create custom middleware, distinct_id helpers, or conditional checks - the SDK handles these
Remember that source code is available in the venv/site-packages directory
posthog is the Python SDK package name
Install dependencies with pip install posthog or pip install -r requirements.txt and do NOT use unquoted version specifiers like >= directly in shell commands
In CLIs and scripts: MUST call posthog.shutdown() before exit or all events are lost
Always use the Posthog() class constructor (instance-based API) instead of module-level posthog.api_key config
Always include enable_exception_autocapture=True in the Posthog() constructor to automatically track exceptions
NEVER send PII in capture() event properties — no emails, full names, phone numbers, physical addresses, IP addresses, or user-generated content
PII belongs in identify() person properties, NOT in capture() event properties. Safe event properties are metadata like message_length, form_type, boolean flags.
Register posthog_client.shutdown with atexit.register() to ensure all events are flushed on exit
The Python SDK has NO identify() method — use posthog_client.set(distinct_id=user_id, properties={...}) to set person properties, or use identify_context(user_id) within a context

Identifying users

Identify users during login and signup events. Refer to the example code and documentation for the correct identify pattern for this framework. If both frontend and backend code exist, pass the client-side session and distinct ID using X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID headers to maintain correlation.

Error tracking

Add PostHog error tracking to relevant files, particularly around critical user flows and API boundaries.

Files

ATTRIBUTION.mdAdded by AutoGineer954 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md3.6 KiB
references/EXAMPLE.md30.0 KiB
references/basic-integration-1.0-begin.md2.1 KiB
references/basic-integration-1.1-edit.md2.5 KiB
references/basic-integration-1.2-revise.md937 B
references/basic-integration-1.3-conclude.md1.6 KiB
references/django.md6.7 KiB
references/identify-users.md8.1 KiB

references/django.md

Django - Docs

PostHog makes it easy to get data about traffic and usage of your Django app. Integrating PostHog enables analytics, custom events capture, feature flags, and more.

This guide walks you through integrating PostHog into your Django app using the Python SDK.

Beta: integration via LLM

Install PostHog for Django in seconds with our wizard by running this prompt with LLM coding agents like Cursor and Bolt, or by running it in your terminal.

npx @posthog/wizard@latest

Learn more

Or, to integrate manually, continue with the rest of this guide.

Installation

To start, run pip install posthog to install PostHog’s Python SDK.

Then, set the PostHog API key and host in your AppConfig in your your_app/apps.py so that's it's available everywhere:

your_app/apps.py

PostHog AI

from django.apps import AppConfig
import posthog
class YourAppConfig(AppConfig):
    name = "your_app_name"
    def ready(self):
        posthog.api_key = '<ph_project_token>'
        posthog.host = 'https://us.i.posthog.com'

You can find your project token and instance address in your project settings.

Next, if you haven't done so already, make sure you add your AppConfig to your settings.py under INSTALLED_APPS:

settings.py

PostHog AI

INSTALLED_APPS = [
    # other apps
    'your_app_name.apps.MyAppConfig',  # Add your app config
]

Lastly, to access PostHog in any file, simply import posthog and call the method you'd like. For example, to capture an event:

Python

PostHog AI

import posthog
def some_request(request):
    with posthog.new_context():
        posthog.identify_context(request.user.id)
        posthog.capture('event_name')

Identifying users

Identifying users is required. Backend events need a distinct_id that matches the ID your frontend uses when calling posthog.identify(). Without this, backend events are orphaned — they can't be linked to frontend event captures, session replays, LLM traces, or error tracking.
See our guide on identifying users for how to set this up.

Django contexts middleware

The Python SDK provides a Django middleware that automatically wraps all requests with a context. This middleware extracts session and user information from request headers and tags all events captured during the request with relevant metadata.

Basic setup

Add the middleware to your Django settings:

Python

PostHog AI

MIDDLEWARE = [
    # ... other middleware
    'posthog.integrations.django.PosthogContextMiddleware',
    # ... other middleware
]

The middleware automatically extracts and uses:

Session ID from the X-POSTHOG-SESSION-ID header, if present
Distinct ID from the X-POSTHOG-DISTINCT-ID header, if present
Current URL as $current_url
Request method as $request_method

All events captured during the request (including exceptions) will include these properties and be associated with the extracted session and distinct ID.

If you are using PostHog on your frontend, the JavaScript Web SDK will add the session and distinct ID headers automatically if you enable tracing headers.

JavaScript

PostHog AI

posthog.init('<ph_project_token>', {
    __add_tracing_headers: ['your-backend-domain.com']
})

Exception capture

By default, the middleware captures exceptions and sends them to PostHog's error tracking. Disable this by setting:

Python

PostHog AI

# settings.py
POSTHOG_MW_CAPTURE_EXCEPTIONS = False

Adding custom tags

Use POSTHOG_MW_EXTRA_TAGS to add custom properties to all requests:

Python

PostHog AI

# settings.py
def add_user_tags(request):
    # type: (HttpRequest) -> Dict[str, Any]
    tags = {}
    if hasattr(request, 'user') and request.user.is_authenticated:
        tags['user_id'] = request.user.id
        tags['email'] = request.user.email
    return tags
POSTHOG_MW_EXTRA_TAGS = add_user_tags

Filtering requests

Skip tracking for certain requests using POSTHOG_MW_REQUEST_FILTER:

Python

PostHog AI

# settings.py
def should_track_request(request):
    # type: (HttpRequest) -> bool
    # Don't track health checks or admin requests
    if request.path.startswith('/health') or request.path.startswith('/admin'):
        return False
    return True
POSTHOG_MW_REQUEST_FILTER = should_track_request

Modifying default tags

Use POSTHOG_MW_TAG_MAP to modify or remove default tags:

Python

PostHog AI

# settings.py
def customize_tags(tags):
    # type: (Dict[str, Any]) -> Dict[str, Any]
    # Remove URL for privacy
    tags.pop('$current_url', None)
    # Add custom prefix to method
    if '$request_method' in tags:
        tags['http_method'] = tags.pop('$request_method')
    return tags
POSTHOG_MW_TAG_MAP = customize_tags

Complete configuration example

Python

PostHog AI

# settings.py
def add_request_context(request):
    # type: (HttpRequest) -> Dict[str, Any]
    tags = {}
    if hasattr(request, 'user') and request.user.is_authenticated:
        tags['user_type'] = 'authenticated'
        tags['user_id'] = str(request.user.id)
    else:
        tags['user_type'] = 'anonymous'
    # Add request info
    tags['user_agent'] = request.META.get('HTTP_USER_AGENT', '')
    return tags
def filter_tracking(request):
    # type: (HttpRequest) -> bool
    # Skip internal endpoints
    return not request.path.startswith(('/health', '/metrics', '/admin'))
def clean_tags(tags):
    # type: (Dict[str, Any]) -> Dict[str, Any]
    # Remove sensitive data
    tags.pop('user_agent', None)
    return tags
POSTHOG_MW_EXTRA_TAGS = add_request_context
POSTHOG_MW_REQUEST_FILTER = filter_tracking
POSTHOG_MW_TAG_MAP = clean_tags
POSTHOG_MW_CAPTURE_EXCEPTIONS = True

All events captured within the request context automatically include the configured tags and are associated with the session and user identified from the request headers.

Next steps

For any technical questions for how to integrate specific PostHog features into Django (such as analytics, feature flags, A/B testing, etc.), have a look at our Python SDK docs.

Alternatively, the following tutorials can help you get started:

Community questions

Ask a question

Was this page useful?

HelpfulCould be better

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an API key, Needs Python

Security

What our scanner noticed· Low risk

Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

PostHog

Publisher

PostHog (Official)

Source

PostHog/skills · skills/posthog/integration/skills/django · commit a5d30e7

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

Also distributed in

PostHog/skills

AutoGineer is not affiliated with or endorsed by PostHog.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download integration-django.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by PostHog

PostHog integration for Django

Workflow

Reference files

Key principles

Framework guidelines

Identifying users

Error tracking

Files

references/django.md

Django - Docs

Beta: integration via LLM

Installation

Identifying users

Django contexts middleware

Basic setup

Exception capture

Adding custom tags

Filtering requests

Modifying default tags

Complete configuration example

Next steps

Community questions

Was this page useful?

Requirements and compatibility

Security

Attribution and licence

Related skills

Claude API

Transformers

Open Notebook

Vision Sft

LLM Evaluation

Lora Qlora Recipes

Download ZIP