Install & Compatibility
Where this runs
tested against v0.72.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 1.034s · 50MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.0s · import 0.692s · 50MB
48MB installed
● package 48MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
statsig
✓ import statsig
✗ from statsig import StatsigServer
While `StatsigServer` exists, the idiomatic way to interact with the SDK is through the top-level `statsig` module functions like `statsig.initialize()`, `statsig.check_gate()`, etc.
StatsigUser
✓ from statsig import StatsigUser
StatsigOptions
✓ from statsig import StatsigOptions
This quickstart demonstrates how to initialize the Statsig Python SDK, define a user, check a feature gate, retrieve a dynamic config, fetch an experiment, log an event, and properly shut down the SDK. Remember to replace `YOUR_SERVER_SECRET_KEY` with your actual server secret from the Statsig console, or set it via the `STATSIG_SERVER_SECRET` environment variable.
import statsig
import os
import asyncio
async def main():
# It is crucial to use a server secret key (sk-...) for the server SDK.
# NEVER expose client keys (pk-..., client-...) in your server-side code.
secret_key = os.environ.get('STATSIG_SERVER_SECRET', 'YOUR_SERVER_SECRET_KEY')
if not secret_key or secret_key == 'YOUR_SERVER_SECRET_KEY':
print("Please set the STATSIG_SERVER_SECRET environment variable or replace 'YOUR_SERVER_SECRET_KEY' in the code.")
return
# Initialize the SDK. This is an asynchronous operation.
print("Initializing Statsig SDK...")
await statsig.initialize(secret_key)
print("Statsig SDK initialized.")
# Define a StatsigUser object with relevant attributes
user = statsig.StatsigUser(
user_id="example-user-123",
email="user@example.com",
country="US",
custom={
"plan": "premium"
},
private_attributes={
"phone_number": "+15551234567"
}
)
# Check a feature gate
if statsig.check_gate(user, "my_feature_gate"):
print("Feature 'my_feature_gate' is ON for the user.")
else:
print("Feature 'my_feature_gate' is OFF for the user.")
# Get a dynamic config
config = statsig.get_config(user, "my_dynamic_config")
print(f"Value for 'my_dynamic_config': {config.value}")
# Get an experiment
experiment = statsig.get_experiment(user, "my_a_b_test")
print(f"Value for 'my_a_b_test': {experiment.value}")
# Log an event
statsig.log_event(user, "product_viewed", value=10.99, metadata={"product_id": "item_xyz"})
# Shut down the SDK. This is crucial for flushing all pending events.
print("Shutting down Statsig SDK...")
await statsig.shutdown()
print("Statsig SDK shut down.")
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
gotchaThe SDK requires a **Server Secret Key** (starts with `sk-`). Using a Client SDK Key (starts with `pk-` or `client-`) will result in initialization failures and prevent the SDK from fetching configurations and evaluating correctly. Server keys should never be exposed in client-side code.fixEnsure you are using the correct server secret key obtained from your Statsig console. Do not confuse it with client keys.
affects: All versions
breakingBoth `statsig.initialize()` and `statsig.shutdown()` are asynchronous operations and **must be awaited**. Failing to `await statsig.initialize()` can lead to the SDK operating with stale or default configurations, and `check_gate`/`get_config` calls may block or return incorrect values. Failing to `await statsig.shutdown()` will result in lost event data as pending events may not be flushed to Statsig servers before your application exits.fixAlways call `await statsig.initialize(secret_key)` at the start of your application and `await statsig.shutdown()` before the application terminates. Ensure your application's entry point uses `asyncio.run()` or similar async executor.
affects: All versions, especially when using recent async patterns.
gotchaThe accuracy of feature gate, dynamic config, and experiment evaluations depends entirely on the attributes provided in the `StatsigUser` object. Incomplete or incorrect user attributes can lead to users being evaluated against the wrong segment or receiving default values, resulting in inconsistent experiences.fixAlways provide the most complete and accurate `StatsigUser` object possible. Include `user_id`, and any custom attributes or private attributes that are used in your Statsig rules. Ensure `user_id` is consistent across sessions.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'statsig'
The 'statsig' library has not been installed in the Python environment where the code is being executed.
AttributeError: module 'statsig' has no attribute 'initialize'
The 'initialize' method is a static method of the 'Statsig' class, not directly available at the top-level 'statsig' module.
fiximport statsig
statsig.Statsig.initialize("YOUR_STATSIG_SERVER_SECRET_KEY") ValueError: Invalid SDK Key provided. Please use a valid SdkKey starting with 'secret-'
The SDK key passed to `Statsig.initialize()` is either missing, empty, or does not adhere to the required 'secret-' prefix format.
fixstatsig.Statsig.initialize("secret-YOUR_SERVER_SECRET_KEY") TypeError: 'dict' object has no attribute 'user_id'
Statsig SDK methods like `check_gate` and `get_config` expect an instance of `statsig.StatsigUser` to represent the user, but a plain dictionary was provided instead.
fixstatsig_user = statsig.StatsigUser(user_id="user-123", email="test@example.com")
statsig.Statsig.check_gate(statsig_user, "my_feature_gate")
Statsig SDK not initialized. Returning default value.
This is a warning indicating that `Statsig.initialize()` was either not called, failed to complete, or was called in an asynchronous context without `await`, leading to subsequent SDK method calls before initialization was finished.
fixEnsure `statsig.Statsig.initialize()` completes successfully before any other SDK methods are invoked. If in an async context, ensure it is awaited: `await statsig.Statsig.initialize("YOUR_STATSIG_SERVER_SECRET_KEY")`. Upgrade
Version history
0.72.1latest on PyPI · released Aug 19, 2026
Audit
Dependencies
httpxrequiredUsed for HTTP communication with Statsig APIs, including logging events and fetching configurations.