HomeGuidesAPI Reference
Submit Documentation FeedbackJoin Developer CommunityOptimizely GitHubOptimizely NuGetLog In

Initialize SDK

This topic describes how to initialize the Optimizely Python SDK in your application.

Use the instantiate method to initialize the Python SDK and instantiate an instance of the Optimizely client class that exposes API methods like the Decide methods. Each client corresponds to the datafile representing the state of a project for a certain environment.


SDK v3.2.0 and higher


The constructor accepts a configuration object to configure Optimizely.

Some parameters are optional because the SDK provides a default implementation, but you may want to override these for your production environments. For example, you may want override these to set up an error handler and logger to catch issues, an event dispatcher to manage network calls, and a User Profile Service to ensure sticky bucketing.


The table below lists the required and optional parameters in Python.

stringThe JSON string representing the project.
Must provide either datafile or sdk_key.
stringOptional string that uniquely identifies the datafile corresponding to project and environment combination.
Must provide either datafile or sdk_key.
EventDispatcherAn event handler to manage network calls.
logging.LoggerA logger implementation to log issues.
BaseErrorHandlerAn error handler object to handle errors.
UserProfileServiceA user profile service.
BooleanSpecifies whether the JSON should be validated. Set to true to skip JSON validation on the schema, or false to perform validation.
BaseConfigManagerImplements optimizely.config_manager.BaseConfigManager.
Responsible for providing get_config method which returns an instance of optimizely.project_config.ProjectConfig.
NotificationCenterInstance of optimizely.notification_center.NotificationCenter.
This option is useful when providing your own optimizely.config_manager.BaseConfigManager implementation, which can use the same NotificationCenter instance.
string(Server-side only) Optimizely SDKs can use an access token (in combination with an sdk_key) to fetch the datafile from an authenticated endpoint. Find your datafile access token in the Optimizely app at Settings>Environments. Select your secure environment, and copy the Datafile access token.
default_decide_optionsarrayArrary of OptimizelyDecideOption enums. When the Optimizely client is constructed with this parameter, it sets default decide options which are applied to all the Decide calls made during the lifetime of the Optimizely client. Additionally, you can pass options to individual Decide methods (does not overrides defaults).
For details on decide options, see OptimizelyDecideOption


Instantiates an instance of the Optimzely class.


In the Python SDK, you can provide either sdkKey or datafile or both.

  • When initializing with just the SDK key, the SDK will poll for datafile changes in the background at regular intervals.
  • When initializing with just the datafile, the SDK will NOT poll for datafile changes in the background.
  • When initializing with both the SDK key and datafile, the SDK will use the given datafile and start polling for datafile changes in the background.

Instantiate using SDK Key (recommended)

In the Python SDK, you only need to pass the SDK key value to instantiate a client. Whenever the experiment configuration changes, the SDK handles the change for you.

Include sdkKey as a string property in the options object you pass to the createInstance method.

When you provide the sdkKey, the SDK instance downloads the datafile associated with that sdkKey. When the download completes, the SDK instance updates itself to use the downloaded datafile.

from optimizely import optimizely
from optimizely.config_manager import PollingConfigManager
sdk_key = '123456'
conf_manager = PollingConfigManager(
   sdk_key = sdk_key,
optimizely = optimizely.Optimizely(config_manager=conf_manager)

Instantiate using datafile

You can also instantiate with a hard-coded datafile. If you don't pass in an SDK key, the Optimizely Client will not automatically sync newer versions of the datafile. Any time you retrieve an updated datafile, just re-instantiate the same client.

For simple applications, all you need to provide to instantiate a client is a datafile specifying the project configuration for a given environment. For most advanced implementations, you'll want to customize the logger or error handler for your specific requirements.

from optimizely import optimizely

# Instantiate an Optimizely client
optimizely = optimizely.Optimizely(datafile)


Enable JSON schema validation

Skipping JSON schema validation enhances performance during instantiation. In the Python SDK, you have control over whether to validate the JSON schema of the datafile when instantiating the client. This example shows how to skip JSON schema validation:

# Skip JSON schema validation (SDK versions 0.1.1 and above)
optimizely = optimizely.Optimizely(datafile,

Use authenticated datafiles in secure environments


Beta feature

Contact your Customer Success Manager if you are interested in becoming an early user of authenticated datafiles as part of the beta secure environment feature.

You can fetch the Optimizely datafile from an authenticated endpoint using a server-side (only) Optimizely SDK. To use an authenticated datafile, download your Optimizely environment's access token from the Optimizely app at Settings>Environments. Select your secure environment, and copy the Datafile access token. The example below shows how to initialize the Optimizely client using an access token and sdk_key, enabling the client to fetch the authenticated datafile and complete initialization.

# fetch the datafile from an authenticated endpoint
sdk_key = '<YOUR_SDK_KEY>'
optimizely = optimizely.Optimizely(sdk_key = sdk_key,
                                          datafile_access_token = access_tkn )

For more information on custom use of the Optimizely datafile, see Manage config (datafile).

Source files

The language/platform source files containing the implementation for Python are at optimizely.py.