Skip to main content


Project description

Thread-pool Controls Build Status codecov

Python helpers to limit the number of threads used in the threadpool-backed of common native libraries used for scientific computing and data science (e.g. BLAS and OpenMP).

Fine control of the underlying thread-pool size can be useful in workloads that involve nested parallelism so as to mitigate oversubscription issues.


  • For users, install the last published version from PyPI:

    pip install threadpoolctl
  • For contributors, install from the source repository in developer mode:

    pip install -r dev-requirements.txt
    flit install --symlink

    then you run the tests with pytest:



Runtime Introspection

Introspect the current state of the threadpool-enabled runtime libraries that are loaded when importing Python packages:

>>> from threadpoolctl import threadpool_info
>>> from pprint import pprint
>>> pprint(threadpool_info())

>>> import numpy
>>> pprint(threadpool_info())
[{'filepath': '/opt/venvs/py37/lib/python3.7/site-packages/numpy/.libs/',
  'internal_api': 'openblas',
  'num_threads': 4,
  'prefix': 'libopenblas',
  'user_api': 'blas',
  'version': ''}]

>>> import xgboost
>>> pprint(threadpool_info())
[{'filepath': '/opt/venvs/py37/lib/python3.7/site-packages/numpy/.libs/',
  'internal_api': 'openblas',
  'num_threads': 4,
  'prefix': 'libopenblas',
  'user_api': 'blas',
  'version': ''},
 {'filepath': '/opt/venvs/py37/lib/python3.7/site-packages/scipy/.libs/',
  'internal_api': 'openblas',
  'num_threads': 4,
  'prefix': 'libopenblas',
  'user_api': 'blas',
  'version': None},
 {'filepath': '/usr/lib/x86_64-linux-gnu/',
  'internal_api': 'openmp',
  'num_threads': 4,
  'prefix': 'libgomp',
  'user_api': 'openmp',
  'version': None}]

Set the maximum size of thread-pools

Control the number of threads used by the underlying runtime libraries in specific sections of your Python program:

from threadpoolctl import threadpool_limits
import numpy as np

with threadpool_limits(limits=1, user_api='blas'):
    # In this block, calls to blas implementation (like openblas or MKL)
    # will be limited to use only one thread. They can thus be used jointly
    # with thread-parallelism.
    a = np.random.randn(1000, 1000)
    a_squared = a @ a

Known limitation

threadpool_limits does not act as expected in nested parallel loops managed by distinct OpenMP runtime implementations (for instance libgomp from GCC and libomp from clang/llvm or libiomp from ICC).

See the test_openmp_nesting() function in tests/ for an example.


To make a release:

pip install flit
flit build

Check the contents of dist/.

If everything is fine, make a commit for the release, tag it, push the tag to github and then:

flit publish

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for threadpoolctl, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size threadpoolctl-1.0.0-py3-none-any.whl (24.4 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size threadpoolctl-1.0.0.tar.gz (17.5 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page