Skip to main content

​
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

​
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"
    }
)

​
API Changes

​
Key Package and Class Changes

FeaturePython Core SDKLegacy Python SDKStatus
Packagestatsig_python_corestatsig⚠️ Renamed
Importfrom statsig_python_core import *from statsig import Statsig⚠️ Change
OptionsStatsigOptionsStatsigOptions✓ Same
UserStatsigUserStatsigUser✓ Same
Initializestatsig.initialize().wait()statsig.initialize()⚠️ Added .wait()
Check Gatestatsig.check_gate()statsig.check_gate()✓ Same
Get Configstatsig.get_dynamic_config()statsig.get_config()⚠️ Renamed
Get Experimentstatsig.get_experiment()statsig.get_experiment()✓ Same
Get Layerstatsig.get_layer()statsig.get_layer()✓ Same
Log Eventstatsig.log_event()statsig.log_event()✓ Same
Shutdownstatsig.shutdown().wait()statsig.shutdown()⚠️ Added .wait()
For more details on the new API, see Python Core SDK documentation.

​
Behavioral Changes

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.
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 .
The ID List functionality is disabled by default.To enable it, set the StatsigOptions flag .
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.

​
StatsigOptions Changes

The table below shows the mapping between legacy SDK options and Server Core SDK options:
Old OptionNew / Notes
apiDeprecated
idlists_thread_limit, logging_interval, enable_debug_logs, events_flushed_callbackDeprecated
timeoutDeprecated (was only for network)
api_for_download_config_specsspecs_url – must complete with endpoint
api_for_get_id_listsid_lists_url – must complete with endpoint
api_for_log_eventlog_event_url – must complete with endpoint
tierenvironment
init_timeoutinit_timeout_ms – applies to overall initialization (suggest adding +1000 ms if enabling UA)
rulesets_sync_intervalspecs_sync_interval_ms (unit: milliseconds)
idlists_sync_intervalid_lists_sync_interval_ms (unit: milliseconds)
local_modedisable_network
event_queue_sizeevent_logging_max_queue_size
data_storeStill supported but interface changed
fallback_to_statsig_apiStill supported
output_logger_levelNow output_log_level
overall_init_timeoutReplaced by init_timeout_ms
observability_client, sdk_error_callbackNow within observability_client interface
custom_loggerNow OutputLoggerProvider interface
bootstrap_values, evaluation_callback, proxy_configs, out_of_sync_threshold_in_s, rules_updated_callbackNot yet supported
1

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.
2

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.
3

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.
4

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.
5

Test Thoroughly

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

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:
⌘I