Configuration Contexts and Global Options

Overview

Just like scikit-learn, the Extension for Scikit-learn* offers configurable options which can be managed locally through a configuration context, or globally through process-wide settings, by extending the configuration-related functions from scikit-learn (see sklearn.config_context for details).

Configurations in the Extension for Scikit-learn* are particularly useful for GPU functionalities and SMPD mode, and are necessary to modify for enabling array API.

Configuration context and global options manager for the Extension for Scikit-learn* can either be imported directly from the module sklearnex, or can be imported from the sklearn module after applying patching.

Note that options in the Extension for Scikit-learn* are a superset of options from scikit-learn, and options passed to the configuration contexts and global settings of the Extension for Scikit-learn* will also affect scikit-learn if the option is supported by it - meaning: the same context manager or global option setter is used for both libraries.

Example usage

Example using the target_offload option to make computations run on a GPU:

With a local context

Here, only the operations from scikit-learn and from the Extension for Scikit-learn* that happen within the ‘with’ block will be affected by the options:

import numpy as np
from sklearnex import config_context
from sklearnex.cluster import DBSCAN

X = np.array([[1., 2.], [2., 2.], [2., 3.],
              [8., 7.], [8., 8.], [25., 80.]], dtype=np.float32)
with config_context(target_offload="gpu"):
    clustering = DBSCAN(eps=3, min_samples=2).fit(X)

As a global option

Here, all computations from scikit-learn and from the Extension for Scikit-learn* that happen after the option is modified are affected:

import numpy as np
from sklearnex import set_config
from sklearnex.cluster import DBSCAN

X = np.array([[1., 2.], [2., 2.], [2., 3.],
              [8., 7.], [8., 8.], [25., 80.]], dtype=np.float32)

set_config(target_offload="gpu") # set it globally
clustering = DBSCAN(eps=3, min_samples=2).fit(X)
set_config(target_offload="auto") # restore it back

API Reference

Note that all of the options accepted by these functions in scikit-learn are also accepted here - these just list the additional options offered by the Extension for Scikit-learn*.

sklearnex.config_context(**new_config)[source]

Context manager for local scikit-learn-intelex configurations.

Parameters:

target_offload (str or dpctl.SyclQueue or None) –
The device used to perform computations, either as a string indicating a name recognized by the SyCL runtime, such as "gpu", "gpu:0", or as a dpctl.SyclQueue object indicating where to move the data.

Assuming SyCL-related dependencies are installed, the list of devices recognized by SyCL can be retrieved through the CLI tool sycl-ls in a shell, or through dpctl.get_devices in a Python process.

String "auto" is also accepted.

Global default: "auto".
allow_fallback_to_host (bool or None) –
If True, allows computations to fall back to host device (CPU) when an unsupported operation is attempted on GPU through target_offload.

Global default: False.
allow_sklearn_after_onedal (bool or None, default=None) –
If True, allows computations to fall back to stock scikit-learn when no accelered version of the operation is available (see Algorithms).

Global default: True.
use_raw_input (bool or None) –
If True, uses the raw input data in some SPMD onedal backend computations without any checks on data consistency or validity. Note that this can be better achieved through usage of array API classes without target_offload. Not recommended for general use.

Global default: False.

Deprecated since version 2026.0.
sklearn_configs (kwargs) – Other settings accepted by scikit-learn. See sklearn.set_config for details.

Warning

Using use_raw_input=True is not recommended for general use as it bypasses data consistency checks, which may lead to unexpected behavior. It is recommended to use the newer array API instead.

Note

Usage of target_offload requires additional dependencies - see GPU support for more information.

Note

All settings, not just those presently modified, will be returned to their previous values when the context manager is exited.