There are 2 steps to implement feature flags in Python:

### Step 1: Evaluate the feature flag value

#### Boolean feature flags

```python
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')
```

#### Multivariate feature flags

```python
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')
```

import IncludePropertyInEvents from "./include-feature-flag-property-in-backend-events.mdx"

<IncludePropertyInEvents />

There are two methods you can use to include feature flag information in your events:

#### Method 1: Include the `$feature/feature_flag_name` property

 In the event properties, include `$feature/feature_flag_name: variant_key`:

```python
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
    },
)
```

#### Method 2: Set `send_feature_flags` to `true`

import PythonSetSendFeatureFlagsTrue from "./feature-flags-code-python-set-send-feature-flags-to-true.mdx"

<PythonSetSendFeatureFlagsTrue />

### Fetching all flags for a user

You can fetch all flag values for a single user by calling `get_all_flags()` or `get_all_flags_and_payloads()`.

This is useful when you need to fetch multiple flag values and don't want to make multiple requests.

```python
posthog.get_all_flags('distinct_id_of_your_user')
posthog.get_all_flags_and_payloads('distinct_id_of_your_user')
```

### Sending `$feature_flag_called` events

Capturing `$feature_flag_called` events enable PostHog to know when a flag was accessed by a user and thus provide [analytics and insights](/docs/product-analytics/insights) on the flag. By default, we send a these event when:

1. You call `posthog.get_feature_flag()` or `posthog.feature_enabled()`, AND
2. It's a new user, or the value of the flag has changed.

> *Note:* Tracking whether it's a new user or if a flag value has changed happens in a local cache. This means that if you reinitialize the PostHog client, the cache resets as well – causing `$feature_flag_called` events to be sent again when calling `get_feature_flag` or `feature_enabled`. PostHog is built to handle this, and so duplicate `$feature_flag_called` events won't affect your analytics.

You can disable automatically capturing `$feature_flag_called` events. For example, when you don't need the analytics, or it's being called at such a high volume that sending events slows things down.

To disable it, set the `send_feature_flag_events` argument in your function call, like so:

```python
is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user', send_feature_flag_events=False)
# will not send `$feature_flag_called` events
```

import PythonOverrideServerProperties from './override-server-properties/python.mdx'

<PythonOverrideServerProperties />

### Request timeout

You can configure the `feature_flags_request_timeout_seconds` parameter when initializing your PostHog client to set a flag request timeout. This helps prevent your code from being blocked in the case when PostHog's servers are too slow to respond. By default, this is set at 3 seconds.

```python
posthog = Posthog('<ph_project_api_key>',
    host='<ph_client_api_host>'
    feature_flags_request_timeout_seconds=3 // Time in second. Default is 3
)
```

### Error handling

When using the PostHog SDK, it's important to handle potential errors that may occur during feature flag operations. Here's an example of how to wrap PostHog SDK methods in an error handler:

```python
def handle_feature_flag(client, flag_key, distinct_id):
    try:
        is_enabled = client.is_feature_enabled(flag_key, distinct_id)
        print(f"Feature flag '{flag_key}' for user '{distinct_id}' is {'enabled' if is_enabled else 'disabled'}")
        return is_enabled
    except Exception as e:
        print(f"Error fetching feature flag '{flag_key}': {str(e)}")
        raise e

# Usage example
try:
    flag_enabled = handle_feature_flag(client, 'new-feature', 'user-123')
    if flag_enabled:
        # Implement new feature logic
    else:
        # Implement old feature logic
except Exception as e:
    # Handle the error at a higher level
```