Flask
PostHog makes it easy to get data about traffic and usage of your Flask app. Integrating PostHog enables analytics, custom events capture, feature flags, error tracking, and more.
This guide walks you through integrating PostHog into your Flask app using the Python SDK.
Supported versions: These docs cover version
8.x.xof the PostHog Python SDK and Flask 2.2 or later. Version7.71.0and later7.x.xreleases also support everything on this page. Both majors require Python 3.10 or higher. Python 3.9 needs6.x.x(pip install 'posthog<7'), which has no Flask integration. Upgrading from7.x.x? Read the migration guide.
Install with the wizard
Run this command in your project directory to add PostHog to your Flask project. The wizard detects your framework, installs the SDK, and sets up your first events.
Or set it up manually by following the rest of this guide.
Installation
To start, run pip install "posthog>=8,<9" to install PostHog’s Python SDK.
Then, initialize PostHog where you'd like to use it. For example, here's how to capture an event in a simple route:
You can find your project token and instance address in your project settings.
Identifying users
Identifying users is required. Backend events need a
distinct_idto associate events with the correct user.In Python, you can do this through a context. All event captures in the same context will be tagged automatically with the correct
distinct_id. Typically, you would set a fresh context and identify at the top of each route.PythonWhen possible, write a small piece of middleware that resolves your authenticated user, wrap a context around the request, and identifies it. Every
capture()downstream is then attributed automatically. The SDK's Django middleware does this automatically and you can replicate it when using the plain Python SDK.
Request contexts
Version 7.66.0 and later of the Python SDK includes a Flask integration that creates a fresh context for every request. It adds the request URL, method, path, route, IP address, and user agent to events captured during the request.
Register the integration after you create your Flask app and PostHog client:
Setting capture_exceptions=True captures unhandled Flask exceptions. Set it to False for request enrichment without automatic exception capture. If you omit it, the integration inherits the client's enable_exception_autocapture setting.
You can also provide:
request_filterto skip both enrichment and automatic exception capture for selected requestsextra_propertiesto add application-specific properties to the request contextcapture_tracing_headersto stop reading PostHog session and distinct ID headers
If you're using PostHog JavaScript Web on the frontend, configure tracing_headers for your Flask backend hostname so browser requests include the session and distinct ID headers.
With SDK 7.71.0 or later, the integration reads these headers by default as analytics context. Clients can set them, so don't use them for authentication or authorization. To stop reading them, set capture_tracing_headers=False when you register the integration.
Identify the request context from your route when you have an authenticated user ID:
Events captured without a context or explicit distinct_id are sent as anonymous events with an auto-generated distinct_id. See the Python SDK docs for more details.
Error tracking
PosthogFlaskIntegration captures unhandled exceptions when you set capture_exceptions=True or enable exception autocapture on its client. It doesn't capture expected HTTP exceptions or exceptions consumed by your application's error handlers.
Call capture_exception() from a custom error handler when you want to report a handled exception:
Next steps
For any technical questions for how to integrate specific PostHog features into Flask (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:





