Python Core SDK Migration Guide

Why Migrate?

Performance: Core evaluates faster than the legacy SDK
New Features: Access to Parameter Stores, CMAB (Contextual Multi-Armed Bandits), observabilityClient, and more
Future Support: All new features and improvements will only be available in Core
Maintenance: The legacy SDK is in maintenance mode and will only receive critical bug fixes

Installation

pip install statsig-python-core

pip install statsig

StatsigUser

User creation is still the same in the new python core SDK.

from statsig_python_core import *

user = StatsigUser(
    user_id="user_123",
    email="user@example.com",
    ip="192.168.0.1",
    user_agent="Mozilla/5.0",
    country="US",
    custom={
        "subscription_level": "premium"
    }
)

from statsig import StatsigUser

user = StatsigUser(
    user_id="user_123",
    email="user@example.com",
    ip="192.168.0.1",
    user_agent="Mozilla/5.0",
    country="US",
    custom={
        "subscription_level": "premium"
    }
)

API Changes

Key Package and Class Changes

Feature	Python Core SDK	Legacy Python SDK	Status
Package	`statsig_python_core`	`statsig`	⚠️ Renamed
Import	`from statsig_python_core import *`	`from statsig import Statsig`	⚠️ Change
Options	`StatsigOptions`	`StatsigOptions`	✓ Same
User	`StatsigUser`	`StatsigUser`	✓ Same
Initialize	`statsig.initialize().wait()`	`statsig.initialize()`	⚠️ Added .wait()
Check Gate	`statsig.check_gate()`	`statsig.check_gate()`	✓ Same
Get Config	`statsig.get_dynamic_config()`	`statsig.get_config()`	⚠️ Renamed
Get Experiment	`statsig.get_experiment()`	`statsig.get_experiment()`	✓ Same
Get Layer	`statsig.get_layer()`	`statsig.get_layer()`	✓ Same
Log Event	`statsig.log_event()`	`statsig.log_event()`	✓ Same
Shutdown	`statsig.shutdown().wait()`	`statsig.shutdown()`	⚠️ Added .wait()

For more details on the new API, see Python Core SDK documentation.

Behavioral Changes

User-Agent Parsing

The SDK now uses a lightweight YAML-based User-Agent parser based on a reduced version of the ua-parser regex definitions.This parser supports the following commonly used browsers:

Chrome
Firefox & Firefox Mobile
Safari & Mobile Safari
Chrome Mobile
Android
Edge & Edge Mobile
IE Mobile
Opera Mobile

If your use case requires identifying less common browsers, you should parse the User-Agent externally before sending it to Statsig.

Lazy Initialization: User-Agent Parser & Country Lookup

User-Agent parsing and country lookup are now lazy-loaded by default to improve SDK initialization performance.If your application relies on these features being ready immediately after initialize(), you can opt in by setting:⚠️ Enabling these options will increase total initialization time.To disable these features entirely, set the StatsigOptions flags and .

ID List Feature

The ID List functionality is disabled by default.To enable it, set the StatsigOptions flag .

Endpoint Changes (v1 to v2)

The core SDK now fetches configuration specs from a new endpoint:

Old: v1/download_config_specs
New: v2/download_config_specs

If you are hosting your own pass-through proxy, ensure it supports and correctly routes the v2 endpoint.

If you are using the Statsig Forward Proxy (SFP), this endpoint migration is handled automatically.

DataStore cache format

** New DataStore cache format**

Old: (Except Node v6+)
- config_spec cache key is: statsig.cache
- IDLists statsig.id_lists
New
- config_spec cache key: statsig|/v2/download_config_specs|plain_text|{SHA256HashedBase64(secretkey)}
- IDLists: We don’t support idlist data store.

StatsigOptions Changes

The table below shows the mapping between legacy SDK options and Server Core SDK options:

Old Option	New / Notes
`api`	Deprecated
`idlists_thread_limit`, `logging_interval`, `enable_debug_logs`, `events_flushed_callback`	Deprecated
`timeout`	Deprecated (was only for network)
`api_for_download_config_specs`	`specs_url` – must complete with endpoint
`api_for_get_id_lists`	`id_lists_url` – must complete with endpoint
`api_for_log_event`	`log_event_url` – must complete with endpoint
`tier`	`environment`
`init_timeout`	`init_timeout_ms` – applies to overall initialization (suggest adding +1000 ms if enabling UA)
`rulesets_sync_interval`	`specs_sync_interval_ms` (unit: milliseconds)
`idlists_sync_interval`	`id_lists_sync_interval_ms` (unit: milliseconds)
`local_mode`	`disable_network`
`event_queue_size`	`event_logging_max_queue_size`
`data_store`	Still supported but interface changed
`fallback_to_statsig_api`	Still supported
`output_logger_level`	Now `output_log_level`
`overall_init_timeout`	Replaced by `init_timeout_ms`
`observability_client`, `sdk_error_callback`	Now within `observability_client` interface
`custom_logger`	Now `OutputLoggerProvider` interface
`bootstrap_values`, `evaluation_callback`, `proxy_configs`, `out_of_sync_threshold_in_s`, `rules_updated_callback`	Not yet supported

Recommended Migration Path

Add the new Dependencies

Add the new SDK package/module and any required platform-specific dependencies for your environment.
Update import or require statements to reference the new SDK namespace or module.
For now - keep the old package in-place, it can be helpful to have both running in parallel momentarily during local testing for your upgrade. If needed (language dependent), you may want to alias the new package.

Update Initialization

Switch to the new initialization syntax. New SDK keys aren’t needed - if you choose to update them, ensure they have the same target apps.
If needed, use the appropriate builder or configuration pattern for setting options, and ensure you migrate the StatsigOptions you use, as some were renamed.

Update User Creation

Migrate to the new format for creating user objects.
If needed, use the builder pattern or updated constructor to set user properties.

Update Method Calls

Starting with a few calls, switch your config checks from the new to old SDK, replacing oldStatsig.getExperiment() with newStatsig.getExperiment()
As you change the package usage, conduct some testing of your service locally or with existing test patterns, to build confidence in the new SDK’s operation.
As you migrate additional calls, update method names if they’ve changed (notably, get_config() to get_dynamic_config)
Once comfortable with the operation of the new SDK from call-by-call migration, consider the use of refactoring tools to migrate the bulk of your remaining calls.

Test Thoroughly

Verify that all of your configs are successfully migrated - run your test suites end-to-end.

Remove old SDK

Remove references to the old SDK, and clean up old initialization and import logic.

Additional Option - Gradual Migration Using Adapter

Use a migration adapter to wrap the new SDK with the old interface.
This allows for incremental migration without updating all call sites at once.
Python Core Migration Adapter

Need Help?

If you encounter any issues during migration, please reach out to us:

SDK Quickstarts

SDK Concepts

Client SDKs

Server SDKs

More SDK Methods

Console API Reference

Statsig CLI

HTTP API Reference

Why Migrate?

Installation

StatsigUser

API Changes

Key Package and Class Changes

Behavioral Changes

StatsigOptions Changes

Recommended Migration Path

Additional Option - Gradual Migration Using Adapter

Need Help?

​Why Migrate?

​Installation

​StatsigUser

​API Changes

​Key Package and Class Changes

​Behavioral Changes

​StatsigOptions Changes

​Recommended Migration Path

​Additional Option - Gradual Migration Using Adapter

​Need Help?

Why Migrate?

Installation

StatsigUser

API Changes

Key Package and Class Changes

Behavioral Changes

StatsigOptions Changes

Recommended Migration Path

Additional Option - Gradual Migration Using Adapter

Need Help?