joblib.parallel_config

class joblib.parallel_config(backend=default(None), *, n_jobs=default(None), verbose=default(0), temp_folder=default(None), max_nbytes=default('1M'), mmap_mode=default('r'), prefer=default(None), require=default(None), inner_max_num_threads=None, **backend_params)

Set the default backend or configuration for Parallel.

This is an alternative to directly passing keyword arguments to the Parallel class constructor. It is particularly useful when calling into library code that uses joblib internally but does not expose the various parallel configuration arguments in its own API.

Parameters
backend: str or ParallelBackendBase instance, default=None

If backend is a string it must match a previously registered implementation using the register_parallel_backend() function.

By default the following backends are available:

  • ‘loky’: single-host, process-based parallelism (used by default),

  • ‘threading’: single-host, thread-based parallelism,

  • ‘multiprocessing’: legacy single-host, process-based parallelism.

‘loky’ is recommended to run functions that manipulate Python objects. ‘threading’ is a low-overhead alternative that is most efficient for functions that release the Global Interpreter Lock: e.g. I/O-bound code or CPU-bound code in a few calls to native code that explicitly releases the GIL. Note that on some rare systems (such as pyodide), multiprocessing and loky may not be available, in which case joblib defaults to threading.

In addition, if the dask and distributed Python packages are installed, it is possible to use the ‘dask’ backend for better scheduling of nested parallel calls without over-subscription and potentially distribute parallel calls over a networked cluster of several hosts.

It is also possible to use the distributed ‘ray’ backend for distributing the workload to a cluster of nodes. See more details in the Examples section below.

Alternatively the backend can be passed directly as an instance.

n_jobs: int, default=None

The maximum number of concurrently running jobs, such as the number of Python worker processes when backend="loky" or the size of the thread-pool when backend="threading". This argument is converted to an integer, rounded below for float. If -1 is given, joblib tries to use all CPUs. The number of CPUs n_cpus is obtained with cpu_count(). For n_jobs below -1, (n_cpus + 1 + n_jobs) are used. For instance, using n_jobs=-2 will result in all CPUs but one being used. This argument can also go above n_cpus, which will cause oversubscription. In some cases, slight oversubscription can be beneficial, e.g., for tasks with large I/O operations. If 1 is given, no parallel computing code is used at all, and the behavior amounts to a simple python for loop. This mode is not compatible with timeout. None is a marker for ‘unset’ that will be interpreted as n_jobs=1 unless the call is performed under a parallel_config() context manager that sets another value for n_jobs. If n_jobs = 0 then a ValueError is raised.

verbose: int, default=0

The verbosity level: if non zero, progress messages are printed. Above 50, the output is sent to stdout. The frequency of the messages increases with the verbosity level. If it more than 10, all iterations are reported.

temp_folder: str or None, default=None

Folder to be used by the pool for memmapping large arrays for sharing memory with worker processes. If None, this will try in order:

  • a folder pointed by the JOBLIB_TEMP_FOLDER environment variable,

  • /dev/shm if the folder exists and is writable: this is a RAM disk filesystem available by default on modern Linux distributions,

  • the default system temporary folder that can be overridden with TMP, TMPDIR or TEMP environment variables, typically /tmp under Unix operating systems.

max_nbytes int, str, or None, optional, default=’1M’

Threshold on the size of arrays passed to the workers that triggers automated memory mapping in temp_folder. Can be an int in Bytes, or a human-readable string, e.g., ‘1M’ for 1 megabyte. Use None to disable memmapping of large arrays.

mmap_mode: {None, ‘r+’, ‘r’, ‘w+’, ‘c’}, default=’r’

Memmapping mode for numpy arrays passed to workers. None will disable memmapping, other modes defined in the numpy.memmap doc: https://numpy.org/doc/stable/reference/generated/numpy.memmap.html Also, see ‘max_nbytes’ parameter documentation for more details.

prefer: str in {‘processes’, ‘threads’} or None, default=None

Soft hint to choose the default backend. The default process-based backend is ‘loky’ and the default thread-based backend is ‘threading’. Ignored if the backend parameter is specified.

require: ‘sharedmem’ or None, default=None

Hard constraint to select the backend. If set to ‘sharedmem’, the selected backend will be single-host and thread-based.

inner_max_num_threads: int, default=None

If not None, overwrites the limit set on the number of threads usable in some third-party library threadpools like OpenBLAS, MKL or OpenMP. This is only used with the loky backend.

backend_params: dict

Additional parameters to pass to the backend constructor when backend is a string.

Notes

Joblib tries to limit the oversubscription by limiting the number of threads usable in some third-party library threadpools like OpenBLAS, MKL or OpenMP. The default limit in each worker is set to max(cpu_count() // effective_n_jobs, 1) but this limit can be overwritten with the inner_max_num_threads argument which will be used to set this limit in the child processes.

New in version 1.3.

Examples

>>> from operator import neg
>>> with parallel_config(backend='threading'):
...     print(Parallel()(delayed(neg)(i + 1) for i in range(5)))
...
[-1, -2, -3, -4, -5]

To use the ‘ray’ joblib backend add the following lines:

>>> from ray.util.joblib import register_ray  
>>> register_ray()  
>>> with parallel_config(backend="ray"):  
...     print(Parallel()(delayed(neg)(i + 1) for i in range(5)))
[-1, -2, -3, -4, -5]

Examples using joblib.parallel_config

Serialization of un-picklable objects

Serialization of un-picklable objects

Using Dask for single-machine parallel computing

Using Dask for single-machine parallel computing