{"id":7928,"library":"amplitude-experiment","title":"Amplitude Experiment Python SDK","description":"The `amplitude-experiment` library is the official Amplitude Experiment Python SDK for server-side instrumentation, enabling feature flagging and A/B testing. It supports both remote and local evaluation of feature flags. The current version is 1.10.1 and the library maintains an active development cycle with frequent updates and bug fixes.","status":"active","version":"1.10.1","language":"en","source_language":"en","source_url":"https://github.com/amplitude/experiment-python-server","tags":["feature flagging","ab testing","experimentation","amplitude","server-side"],"install":[{"cmd":"pip install amplitude-experiment","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for streaming flag configurations, introduced in v1.8.1.","package":"sseclient-py","optional":false},{"reason":"Required for data serialization, introduced in v1.6.3.","package":"dataclasses-json","optional":false},{"reason":"Requires Python 3.6 or higher, but less than 4.","package":"python","optional":false}],"imports":[{"note":"The primary `Experiment` class is available directly under the top-level package.","wrong":"from amplitude_experiment.experiment import Experiment","symbol":"Experiment","correct":"from amplitude_experiment import Experiment"},{"note":"Used for remote evaluation, initialized via `Experiment.initialize_remote()`.","symbol":"RemoteEvaluationClient","correct":"from amplitude_experiment import RemoteEvaluationClient"},{"note":"Used for local evaluation, initialized via `Experiment.initialize_local()`.","symbol":"LocalEvaluationClient","correct":"from amplitude_experiment import LocalEvaluationClient"},{"note":"Essential for defining the user context for flag evaluation.","symbol":"User","correct":"from amplitude_experiment import User"},{"note":"Configuration options for remote evaluation.","symbol":"RemoteEvaluationConfig","correct":"from amplitude_experiment import RemoteEvaluationConfig"},{"note":"Configuration options for local evaluation.","symbol":"LocalEvaluationConfig","correct":"from amplitude_experiment import LocalEvaluationConfig"}],"quickstart":{"code":"import os\nfrom amplitude_experiment import Experiment, User\n\n# Get your deployment's API key from environment variables\nAPI_KEY = os.environ.get('AMPLITUDE_EXPERIMENT_API_KEY', 'YOUR_DEPLOYMENT_KEY')\n\n# Initialize the experiment remote evaluation client\n# It's recommended to initialize the client once on application startup.\nexperiment = Experiment.initialize_remote(API_KEY)\n\n# Define a user for whom variants should be fetched\nuser = User(\n    device_id=\"abcdefg\",\n    user_id=\"user@company.com\",\n    user_properties={'premium': True, 'country': 'USA'}\n)\n\nasync def get_variants_and_evaluate():\n    try:\n        # Fetch variants for the user asynchronously\n        variants = await experiment.fetch_v2(user)\n\n        # Access a flag's variant\n        feature_flag_key = 'your-feature-flag-key'\n        variant = variants.get(feature_flag_key)\n\n        if variant:\n            print(f\"Variant for '{feature_flag_key}': {variant.value}\")\n            if variant.value == 'on':\n                # Implement 'on' behavior\n                print(\"Feature is ON for this user.\")\n            elif variant.value == 'control':\n                # Implement 'control' behavior\n                print(\"User is in control group.\")\n            else:\n                # Implement other variant behavior\n                print(f\"User is in variant: {variant.value}\")\n        else:\n            print(f\"Flag '{feature_flag_key}' not found or variant is None.\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n\n# In a real application, you would call get_variants_and_evaluate() \n# within an async context, e.g., using asyncio.run()\n# import asyncio\n# asyncio.run(get_variants_and_evaluate())","lang":"python","description":"This quickstart demonstrates how to initialize the Amplitude Experiment client for remote evaluation, define a user, fetch feature flag variants, and access a specific flag's value. The API key should be a server-side deployment key. For local evaluation, use `Experiment.initialize_local()` and `experiment.start()` followed by `experiment.evaluate()`."},"warnings":[{"fix":"Review the release notes and migration guides for the specific major version you are upgrading to. Test your application thoroughly after any major version update.","message":"Major version upgrades (e.g., v1.x.x to v2.x.x) typically introduce breaking changes in public interfaces, behaviors, or semantics. Always consult the official upgrade guidelines before updating to a new major version.","severity":"breaking","affected_versions":"All major versions"},{"fix":"Ensure that the `device_id` and `user_id` provided to the `User` object for fetching variants are identical to those used by your Amplitude Analytics instrumentation for tracking events. Implement a consistent identity resolution strategy across your client and server-side SDKs.","message":"Inconsistent bucketing or 'variant jumping' can occur if the `device_id` or `user_id` used for fetching variants differs from the IDs used to track subsequent exposure events in Amplitude Analytics. This often points to an identity mismatch in implementation.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When initializing your client, pass a `RemoteEvaluationConfig` or `LocalEvaluationConfig` object with `server_zone='EU'`: `Experiment.initialize_remote(API_KEY, config=RemoteEvaluationConfig(server_zone='EU'))`.","message":"If you are using Amplitude's EU data center, you must explicitly configure the `server_zone` option during client initialization to `'EU'`, otherwise, data will be routed to the US data center by default.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Choose alternative names or values for your feature flag variants. Avoid 'off' to prevent unexpected behavior with fallback assignments.","message":"Do not assign a variant a name or value of 'off'. This value is explicitly reserved by Amplitude Experiment for users in the 'OFF/FALLBACK' bucket, which is used when Experiment cannot assign a user to a treatment group.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure you have the correct import statement: `from amplitude_experiment import Experiment, User, RemoteEvaluationConfig, RemoteEvaluationClient`.","cause":"The `Experiment` class (or other Amplitude Experiment symbols) was not correctly imported.","error":"NameError: name 'Experiment' is not defined"},{"fix":"Always check if the variant exists before accessing its properties using `variants.get('YOUR-FLAG-KEY')` or by checking `if variant:` before proceeding. Verify the flag key in your Amplitude Experiment dashboard and ensure the flag is enabled for the correct deployment and user.","cause":"Attempting to access a feature flag variant that does not exist in the fetched variants, or the fetch operation failed to return a variant for the specified key. This could be due to an incorrect flag key, the flag not being enabled for the deployment, or the user not qualifying for any variants.","error":"KeyError: 'YOUR-FLAG-KEY' or AttributeError: 'NoneType' object has no attribute 'value'"},{"fix":"Verify your network connectivity. If using an EU data center, ensure `server_zone='EU'` is correctly configured. For custom endpoints, check the `server_url` in your `RemoteEvaluationConfig`.","cause":"Network issues preventing the SDK from reaching Amplitude's servers, or an incorrect `server_url` or `server_zone` configuration.","error":"Failed to connect to host 'api.amplitude.com'"}]}