Install & Compatibility
Where this runs
tested against v6.2.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.854s · 26.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.2s · import 0.796s · 27MB
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Flagsmith
✓ from flagsmith import Flagsmith
Initializes the Flagsmith client, retrieves environment flags, checks feature status, gets feature values, and demonstrates how to get flags for a specific identity with traits. It highlights the use of local evaluation for performance and secret management via environment variables.
import os
from flagsmith import Flagsmith
# Replace 'YOUR_ENVIRONMENT_KEY' with your actual Flagsmith Environment Key
# It's recommended to use environment variables for keys in production.
# Server-side Environment Keys begin with 'ser.'
environment_key = os.environ.get('FLAGSMITH_ENVIRONMENT_KEY', 'YOUR_ENVIRONMENT_KEY')
# Initialize Flagsmith client
# enable_local_evaluation=True is recommended for production for performance
# and resilience, as it polls the API in a separate thread.
flagsmith = Flagsmith(
environment_key=environment_key,
enable_local_evaluation=True
)
# Wait for initial flags to be loaded if using local evaluation
# In a real application, you might want to handle this asynchronously
# or with a proper startup sequence.
flagsmith.update_environment()
# Get all flags for the environment
environment_flags = flagsmith.get_environment_flags()
# Check if a feature is enabled
if environment_flags.is_feature_enabled('my_feature'):
print("My feature is enabled!")
# Get a feature value
feature_value = environment_flags.get_feature_value('another_feature')
print(f"Value of 'another_feature': {feature_value}")
# Get flags for an identity
# Traits will automatically be persisted against the identity in Remote Evaluation mode.
# In Local Evaluation mode, only traits provided at runtime are used.
identity_flags = flagsmith.get_identity_flags(identifier='test_user_123', traits={'plan': 'premium'})
if identity_flags.is_feature_enabled('premium_feature'):
print("Premium feature is enabled for test_user_123!")
# Clean up / close the Flagsmith client (important for local evaluation threads)
flagsmith.close()
Debug
Known issues
breakingFlagsmith Python SDK version 3.5.0 introduced a dependency on Pydantic V2. Projects still using Pydantic V1 will encounter compatibility issues.fixUpgrade Pydantic to V2, or for temporary compatibility, change pydantic imports to `pydantic.v1` and use tools like `bump-pydantic` to assist migration.
affects: >=3.5.0, <4.0.0
breakingMajor versions 4.0.0 and 5.0.0 included breaking changes. The changelog on GitHub should be consulted for specific migration steps. These often involve updates to the SDK's internal engine or API interactions.fixRefer to the official Flagsmith Python SDK `CHANGELOG.md` on GitHub or the Flagsmith documentation for detailed migration guides relevant to your upgrade path.
affects: >=4.0.0, >=5.0.0
gotchaServer-side SDKs require a Server-side Environment Key, which starts with `ser.`. Using a Client-side key will lead to authentication failures or incorrect behavior. These keys should be treated as secret.fixAlways generate and use a Server-side Environment Key for your Python applications. Ensure it's stored securely, preferably via environment variables, and never exposed publicly.
affects: All
gotchaWhen using `enable_local_evaluation=True`, the SDK fetches the environment document in a separate thread. Ensure proper initialization and shutdown procedures to avoid resource leaks or outdated flag evaluations. The `close()` method should be called when the application exits.fixCall `flagsmith.close()` when your application is shutting down to properly terminate background threads. During startup, allow sufficient time for the initial environment document to be fetched before making flag evaluations, or implement retry mechanisms.
affects: All
gotchaRemote Evaluation mode makes an API call for every `get_environment_flags()` or `get_identity_flags()` request, which can introduce latency. Local Evaluation mode can improve performance but evaluates flags based on a locally cached environment document.fixFor performance-critical applications, especially in production, enable local evaluation (`enable_local_evaluation=True`) to minimize network latency. Understand the implications for real-time flag updates versus polling frequency.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flagsmith'
The 'flagsmith' Python package is not installed in your current Python environment.
fixInstall the package using pip: `pip install flagsmith`
TypeError: Flagsmith.__init__ missing 1 required positional argument: 'environment_key'
The 'environment_key' argument is required when initializing the Flagsmith client but was not provided.
fixProvide your Flagsmith environment key during client initialization: `flagsmith.Flagsmith(environment_key="YOUR_ENVIRONMENT_KEY")`
ValueError: environment_key is required
The 'environment_key' was provided as an empty or None string when initializing the Flagsmith client.
fixEnsure that a valid, non-empty environment key string is passed to the Flagsmith client: `flagsmith.Flagsmith(environment_key="YOUR_ACTUAL_ENVIRONMENT_KEY")`
requests.exceptions.HTTPError: 403 Client Error: Forbidden for url: ...
This usually indicates that the Flagsmith API key (environment key) used is incorrect or you are attempting to use a client-side environment key with a server-side SDK (or vice-versa), which leads to an authentication failure.
fixVerify that you are using the correct server-side environment key for your Flagsmith Python SDK and that it has the necessary permissions. Double-check your key in the Flagsmith dashboard for the specific environment.
AttributeError: 'Flag' object has no attribute 'non_existent_attribute'
You are attempting to access an attribute or property on a 'Flag' object that does not exist or is misspelled. This often happens when trying to get a flag's value or status using an incorrect method name.
fixUse the correct methods to access flag properties, such as `is_feature_enabled('your_flag_name')` for its boolean status or `get_feature_value('your_flag_name')` for its string value. Ensure the flag name itself is correct. Upgrade
Version history
6.2.1latest on PyPI · released Aug 14, 2026
Audit
Dependencies
pydanticrequiredUsed by the underlying Flagsmith engine. Compatibility issues may arise with Pydantic V1 in older SDK versions.