> ## Documentation Index
> Fetch the complete documentation index at: https://statsig-4b2ff144-serverless-cloudflare.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Python Core SDK Migration Guide
> Migrate from the legacy Python Server SDK to the new Python Core SDK
export const waitForUserAgentInit_0 = "wait_for_user_agent_init"
export const waitForCountryLookupInit_0 = "wait_for_country_lookup_init"
export const disableUserAgentParsing_0 = "disable_user_agent_parsing"
export const disableCountryLookup_0 = "disable_country_lookup"
export const enableIdLists_0 = "enable_id_lists"
export const sdkType_0 = "Python"
## Why Migrate?
* **Performance**: {sdkType_0} 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 {sdkType_0} Core
* **Maintenance**: The legacy {sdkType_0} SDK is in maintenance mode and will only receive critical bug fixes
## Installation
```bash Python Core theme={null}
pip install statsig-python-core
```
```bash Python Legacy theme={null}
pip install statsig
```
## StatsigUser
User creation is still the same in the new python core SDK.
```python Python Core theme={null}
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"
}
)
```
```python Python Legacy theme={null}
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](/server-core/python-core).
## Behavioral Changes
The SDK now uses a lightweight YAML-based User-Agent parser based on a reduced version of the [ua-parser regex definitions](https://github.com/statsig-io/statsig-server-core/blob/00ad0e4024ca5d30f21892c8f2f23e836165a509/statsig-rust/resources/ua_parser_regex_lite.yaml#L4).
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:
* {waitForUserAgentInit_0}
* {waitForCountryLookupInit_0}
⚠️ Enabling these options will increase total initialization time.
To **disable** these features entirely, set the `StatsigOptions` flags {disableUserAgentParsing_0} and {disableCountryLookup_0}.
The ID List functionality is **disabled by default**.
To enable it, set the `StatsigOptions` flag {enableIdLists_0}.
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 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 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.
* 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.
* Migrate to the new format for creating user objects.
* If needed, use the builder pattern or updated constructor to set user properties.
* 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.
* Verify that all of your configs are successfully migrated - run your test suites end-to-end.
* 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](https://github.com/statsig-io/statsig-server-core-migration-adapters/blob/main/python_core_migration_adapter.py)
## Need Help?
If you encounter any issues during migration, please reach out to us:
* [Statsig Slack Community](https://statsig.com/slack)
* [GitHub Issues](https://github.com/statsig-io/statsig-server-core/issues)