Skip to content
Featureflip Docs

Python Feature Flags Quickstart

This guide gets you from zero to evaluating a feature flag in a Python application. The SDK is synchronous and thread-safe.

Prerequisites

Section titled “Prerequisites”
  • A Featureflip account with at least one feature flag created
  • An SDK key from your environment settings
  • Python 3.10+

Install

Section titled “Install”
Terminal window
pip install featureflip

Initialize the client

Section titled “Initialize the client”
from featureflip import FeatureflipClient, Config


config = Config(base_url="https://eval.featureflip.io")


client = FeatureflipClient(sdk_key="your-sdk-key", config=config)

The client fetches your flag configuration on startup and blocks until initialization completes. If you prefer, set the FEATUREFLIP_SDK_KEY environment variable and omit the sdk_key parameter:

client = FeatureflipClient(config=config)

Evaluate a flag

Section titled “Evaluate a flag”
show_banner = client.variation("new-banner", {"user_id": "user-123"}, default=False)


if show_banner:
    print("Showing the new banner")
else:
    print("Using the default experience")

The variation() method works for all flag types. The default argument is returned when the flag is not found or evaluation fails.

color = client.variation("banner-color", {"user_id": "user-123"}, default="blue")
limit = client.variation("rate-limit", {"user_id": "user-123"}, default=100)

Clean up

Section titled “Clean up”

Close the client when your application shuts down to flush pending analytics events and stop background connections. The recommended approach is a context manager:

from featureflip import FeatureflipClient, Config


config = Config(base_url="https://eval.featureflip.io")


with FeatureflipClient(sdk_key="your-sdk-key", config=config) as client:
    result = client.variation("new-banner", {"user_id": "user-123"}, default=False)
    print(f"Flag value: {result}")

If you are not using a context manager, call client.close() explicitly.

How it works

Section titled “How it works”

The Python SDK evaluates flags locally in your process — variation() is a synchronous call that reads from an in-memory dictionary, so it works naturally in Django views, Flask routes, or any synchronous Python code without blocking the request.

On initialization, the client fetches the full flag configuration over HTTPS and then opens a background thread to maintain an SSE streaming connection. This thread receives configuration updates in near-real-time; if SSE is unavailable, it falls back to polling every 30 seconds. The in-memory flag store is protected by a threading.Lock, making it safe to call variation() from multiple threads in a WSGI server like Gunicorn with threaded workers. The GIL ensures the lock operations themselves are fast, so contention is negligible in practice.

Use the context manager pattern (with FeatureflipClient(...) as client) to ensure the background thread and SSE connection are cleaned up on shutdown. If the connection drops, the SDK continues returning the last known flag values until it reconnects.

Troubleshooting

Section titled “Troubleshooting”

Client initialization is slow or times out

Verify your SDK key and that your application can reach eval.featureflip.io over HTTPS. If you are in a restricted network environment, check that outbound HTTPS traffic is not blocked by a firewall or proxy. The base_url parameter must include the protocol (https://).

variation() returns the default value for every flag

Check that the flag key matches exactly (keys are case-sensitive) and that the flag is enabled in the environment matching your SDK key. Also verify you are passing the context as a dictionary with a user_id key — without it, targeting rules that depend on user identity will not match.

ImportError or ModuleNotFoundError after install

Make sure you installed featureflip (the PyPI package name), not a similarly named package. If you are using a virtual environment, confirm it is activated before running your script. Run pip show featureflip to verify the package is installed in the correct environment.

Next steps

Section titled “Next steps”