Feature Flags Python

PostHog feature flags for Python

This skill helps you add PostHog feature flags to Python applications.

Reference files

• references/python.md - Python feature flags installation - docs
• references/adding-feature-flag-code.md - Adding feature flag code - docs
• references/best-practices.md - Feature flag best practices - docs

Consult the documentation for API details and framework-specific patterns.

Key principles

• Environment variables: Always use environment variables for PostHog keys. Never hardcode them.
• Minimal changes: Add feature flag code alongside existing logic. Don't replace or restructure existing code.
• Boolean flags first: Default to boolean flag checks unless the user specifically asks for multivariate flags.
• Server-side when possible: Prefer server-side flag evaluation to avoid UI flicker.

PostHog MCP tools

Check if a PostHog MCP server is connected. If available, look for tools related to feature flag management (creating, listing, updating, deleting flags). Use these tools to manage flags directly in PostHog rather than requiring the user to do it manually in the dashboard.

Framework guidelines

• 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

Feature flag best practices - Docs

1\. Use a reverse proxy

Ad blockers have the potential to disable your feature flags, which can lead to bad experiences, such as users seeing the wrong version of your app, or missing a new feature rollout.

To avoid this, deploy a reverse proxy, which enables you to make requests and send events to PostHog Cloud using your own domain.

This means that requests are less likely to be intercepted by tracking blockers, and your feature flags are more likely to work as intended. You'll also capture more usage data.

PostHog offers a free managed reverse proxy, or you can run your own. See our reverse proxy docs for more.

2\. Call your flag in as few places as possible

It should be easy to understand how feature flags affect your code. The more locations a flag is in, the more likely it is to cause problems. For example, a developer could remove the flag in one place but forget to remove it in another.

If you expect to use a feature flag in multiple places, it's a good idea to wrap the flag in a single function or method. For example:

JavaScript

PostHog AI

function useBetaFeature() {
    return posthog.isFeatureEnabled('beta-feature')
}

3\. Targeting

PostHog evaluates flags based on the user's distinct ID, having different IDs can cause the same user to receive different flag values across different sessions, devices, and platforms. By identifying them, you can ensure consistent flag values.

The same applies to identifying groups for group-level flags.

For flags targeting anonymous users, such as signup flows or landing page experiments, consider using device bucketing instead. This evaluates the flag based on the device ID, ensuring a consistent experience on the device even after the user logs in.

4\. Use server-side local evaluation for faster flags

Evaluating feature flags requires making a request to PostHog for each flag. However, you can improve performance by evaluating flags locally. Instead of making a request for each flag, PostHog will periodically request and store feature flag definitions locally, enabling you to evaluate flags without making additional requests.

Evaluate flags locally when possible, since this enables you to resolve flags faster and with fewer API calls. See our docs on local evaluation for more details.

5\. Bootstrap flags on the client to make them available immediately

Since there is a delay between initializing PostHog and fetching feature flags, feature flags are not always available immediately. This makes them unusable if you want to do something like redirecting a user to a different page based on a feature flag.

To have your feature flags available immediately, you can initialize PostHog with precomputed values until it has had a chance to fetch them. This is called bootstrapping.

See our docs on bootstrapping for more details on how to do this.

6\. Naming tips

Good naming conventions for your flags makes them easier to understand and maintain. Below are tips for naming your flags:

• Use descriptive names. For example, is_v2_billing_dashboard_enabled is much clearer than is_dashboard_enabled.

• Use name "types". This helps organize them and makes their purpose clear. Types might include experiments, releases, and permissions. For example, instead of new-billing, they would be new-billing-experiment or new-billing-release.

• Name flags to reflect their return type. For example, is_premium_user for a boolean, enabled_integrations for an array, or selected_theme for a single string.

• Use positive language for boolean flags. For example, is_premium_user instead of is_not_premium_user. This helps avoid double negatives when checking the flag value (e.g. if !is_not_premium_user is confusing).

7\. Roll out progressively

When testing a change behind a feature flag, it is best to roll it out to a small group of users and increase that group over time. This is also known as a phased rollout. It enables you to identify any potential issues ahead of the full release.

For example, at PostHog we often roll out the flag to just the responsible developer. It then moves on to the internal team, then beta users, and finally into a full rollout. This enables us to test in production, get multiple rounds of feedback, identify issues, and polish the feature before the full release.

8\. Clean up after yourself

Leaving flags in your code for too long can confuse future developers and create technical debt, especially if it's already rolled out and integrated. Be sure to remove stale flags once they are completely rolled out or no longer needed.

When you have many flags to clean up, use bulk delete to select and delete multiple flags at once. Select flags using checkboxes (shift-click to select a range), or filter by name or status and use "select all matching" to select all flags that match your criteria. PostHog validates that flags aren't used by experiments, early access features, or other dependent flags before deletion.

9\. Fallback to working code

It's possible that a feature flag will return an unexpected value. For example, if the flag is disabled or failed to load due to a network error.

In this case, its best to check that the feature flag returns a valid expected value before using it. If it isn't, fallback to working code.

10\. Use dependencies for complex rollouts

For sophisticated feature rollouts, consider using feature flag dependencies where one flag's activation depends on another flag's state. This is useful for:

• Enabling complex features only after foundational components are active
• Running experiments only on users with specific features enabled
• Creating safety mechanisms where critical flags must be enabled first

When using dependencies, keep the dependency chains simple and avoid circular dependencies.

11\. Reducing your bill

We aim to be significantly cheaper than our competitors. To help you reduce your bill, we've created a dedicated guide to estimating and reducing your feature flag costs.

12\. Consistent flag evaluations across frontend and backend

For feature flags with flag persistence enabled and used across both your frontend and backend, you will need to do one of the following to ensure the evaluation result of the flag is consistent between both environments:

1. Identify the user on the frontend and use the same identified distinct ID when evaluating the flag on the backend.

JavaScript

PostHog AI

// Frontend: Identify the user
posthog.identify('user123')
// Backend: Use the same distinct ID
const flagValue = await posthog.getFeatureFlag('my-flag', 'user123')

2. If you are unable to call identify on the frontend, and only have access to the anonymous distinct ID when evaluating the flag on the backend, you can include the anonymous distinct ID as a person property override in the getFeatureFlag call.

JavaScript

PostHog AI

// Frontend: Get the anonymous ID (before identify is called)
const anonId = posthog.getAnonymousId()
// Backend: Pass the anonymous ID as a person property override
const flagValue = await posthog.getFeatureFlag(
  'my-flag',
  'user123', // identified distinct ID
  {
    personProperties: {
      $anon_distinct_id: anonId
    }
  }
)

Community questions

Ask a question

Was this page useful?

HelpfulCould be better

Python feature flags installation - Docs

1. 1

Install the package

Required

Install the PostHog Python library using pip:

Terminal

PostHog AI

    pip install posthog

2. 2

Initialize PostHog

Required

Initialize the PostHog client with your project token and host from your project settings:

Python

PostHog AI

    from posthog import Posthog
    posthog = Posthog(
        project_api_key='<ph_project_token>',
        host='https://us.i.posthog.com'
    )

Django integration

If you're using Django, check out our Django integration for automatic request tracking.

3. 3

Send events

Recommended

Once installed, PostHog will automatically start capturing events. You can also manually send events to test your integration:

Capture custom events by calling the capture method with an event name and properties:

Python

PostHog AI

    import posthog
    posthog.capture('user_123', 'user_signed_up', properties={'example_property': 'example_value'})

4. 4

Evaluate boolean feature flags

Required

Check if a feature flag is enabled:

    is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')
    if is_my_flag_enabled:
        # Do something differently for this user
        # Optional: fetch the payload
        matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')

5. 5

Evaluate multivariate feature flags

Optional

For multivariate flags, check which variant the user has been assigned:

    enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')
    if enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant
        # Do something differently for this user
        # Optional: fetch the payload
        matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')

6. 6

Include feature flag information in events

Required

If you want to use your feature flag to breakdown or filter events in your insights, you'll need to include feature flag information in those events. This ensures that the feature flag value is attributed correctly to the event.

Note: This step is only required for events captured using our server-side SDKs or API.

Set send_feature_flags (recommended)

Set send_feature_flags to True in your capture call:

Python

PostHog AI

    posthog.capture(
        distinct_id="distinct_id_of_the_user",
        event='event_name',
        send_feature_flags=True
    )

Include $feature property

Include the $feature/feature_flag_name property in your event properties:

Python

PostHog AI

    posthog.capture(
        "event_name",
        distinct_id="distinct_id_of_the_user",
        properties={
            "$feature/feature-flag-key": "variant-key"  # replace feature-flag-key with your flag key. Replace 'variant-key' with the key of your variant
        },
    )

7. 7

Override server properties

Optional

Sometimes, you may want to evaluate feature flags using properties that haven't been ingested yet, or were set incorrectly earlier. You can provide properties to evaluate the flag with:

    posthog.get_feature_flag(
        'flag-key',
        'distinct_id_of_the_user',
        person_properties={'property_name': 'value'},
        groups={
            'your_group_type': 'your_group_id',
            'another_group_type': 'your_group_id'},
        group_properties={
            'your_group_type': {'group_property_name': 'value'},
            'another_group_type': {'group_property_name': 'value'}
        },
    )

8. 8

Running experiments

Optional

Experiments run on top of our feature flags. Once you've implemented the flag in your code, you run an experiment by creating a new experiment in the PostHog dashboard.

9. 9

Next steps

Recommended

Now that you're evaluating flags, continue with the resources below to learn what else Feature Flags enables within the PostHog platform.

Community questions

Ask a question

Was this page useful?

HelpfulCould be better