Get Started with Intel® oneAPI Threading Building Blocks (oneTBB)

ID 772618
Date 3/31/2023

A newer version of this document is available. Customers should click here to go to the newest version.

Get Started with oneAPI Threading Building Blocks (oneTBB)

oneAPI Threading Building Blocks (oneTBB) is a runtime-based parallel programming model for C++ code that uses threads. It consists of a template-based runtime library to help you harness the latent performance of multi-core processors.

oneTBB enables you to simplify parallel programming by breaking computation into parallel running tasks. Within a single process, parallelism is carried out through threads, an operating system mechanism that allows the same or different sets of instructions to be executed simultaneously.

Here you can see one of the possible executions of tasks by threads.

Use oneTBB to write scalable applications that:

  • Specify logical parallel structure instead of threads

  • Emphasize data-parallel programming

  • Take advantage of concurrent collections and parallel algorithms

oneTBB supports nested parallelism and load balancing. It means that you can use the library without being worried about oversubscribing a system.

oneTBB is available as a stand-alone product and as part of the Intel® oneAPI Base Toolkit.

System Requirements

Refer to the oneTBB System Requirements.

Download Intel(R) oneAPI Threading Building Blocks (oneTBB)

Download oneTBB as a stand-alone product or as a part of the Intel(R) oneAPI Base Toolkit. See Installation Guide for a stand-alone version (Windows* OS and Linux* OS) and Intel(R) oneAPI Toolkits Installation Guide.

Before You Begin

After installing oneTBB, you need to set the environment variables:

  1. Go to the oneTBB installation directory (<install_dir>). By default, <install_dir> is the following:

    • On Linux* OS:

      • For superusers (root): /opt/intel/oneapi

      • For ordinary users (non-root): $HOME/intel/oneapi

    • On Windows* OS:

      • <Program Files>\Intel\oneAPI

  2. Set the environment variables, using the script in <install_dir>, by running

    • On Linux* OS:

      vars.{sh|csh} in <install_dir>/tbb/latest/env

    • On Windows* OS:

      vars.bat in <install_dir>/tbb/latest/env


Below you can find a typical example for a oneTBB algorithm. The sample calculates a sum of all integer numbers from 1 to 100.

int sum = oneapi::tbb::parallel_reduce(oneapi::tbb::blocked_range<int>(1,101), 0,
   [](oneapi::tbb::blocked_range<int> const& r, int init) -> int {
      for (int v = r.begin(); v != r.end(); v++  ) {
         init += v;
      return init;
   [](int lhs, int rhs) -> int {
      return lhs + rhs;

oneAPI Threading Building Blocks (oneTBB) and pkg-config tool

The pkg-config tool is used to simplify the compilation line by retrieving information about packages from special metadata files. It helps avoid large hard-coded paths and makes compilation more portable.

Compile a program using pkg-config

To compile a test program test.cpp with oneTBB on Linux* OS and macOS*, provide the full path to search for include files and libraries, or provide a simple line like this:

g++ -o test test.cpp $(pkg-config --libs --cflags tbb)


--cflags provides oneTBB library include path:

$ pkg-config --cflags tbb``

--libs provides the Intel(R) oneTBB library name and the search path to find it:

$ pkg-config –libs tbb
     -L<path to>tbb/latest/lib/pkgconfig/../..//lib/intel64/gcc4.8 -ltbb
For Windows* OS, additionally use the --msvc-syntax option flag that converts the compiling and linking flags in an appropriate mode.

Hybrid CPU and NUMA Support

If you need NUMA/Hybrid CPU support in oneTBB, you need to make sure that HWLOC* is installed on your system.

HWLOC* (Hardware Locality) is a library that provides a portable abstraction of the hierarchical topology of modern architectures (NUMA, hybrid CPU systems, etc). oneTBB relies on HWLOC* to identify the underlying topology of the system to optimize thread scheduling and memory allocation.

Without HWLOC*, oneTBB may not take advantage of NUMA/Hybrid CPU support. Therefore, it’s important to make sure that HWLOC* is installed before using oneTBB on such systems.

Check HWLOC* on the System

To check if HWLOC* is already installed on your system, run hwloc-ls:

  • For Linux* OS, in the command line.

  • For Windows* OS, in the command prompt.

If HWLOC* is installed, the command displays information about the hardware topology of your system. If it is not installed, you receive an error message saying that the command hwloc-ls could not be found.

For Hybrid CPU support, make sure that HWLOC* is version 2.5 or higher. For NUMA support, install HWLOC* version 1.11 or higher.

Install HWLOC*

To install HWLOC*, visit the official Portable Hardware Locality website (

  • For Windows* OS, binaries are available for download.

  • For Linux* OS, only the source code is provided and binaries should be built.

On Linux* OS, HWLOC* can be also installed with package managers, such as APT*, YUM*, etc. To do so, run: sudo apt install hwloc.

For Hybrid CPU support, make sure that HWLOC* is version 2.5 or higher. For NUMA support, install HWLOC* version 1.11 or higher.

Find more

Use these resources if you need support with oneTBB.

Release Notes

Find up-to-date information about the product, including detailed notes, known issues, and changes.

Documentation: Developer Guide and API Reference

Learn to use oneTBB.


Find oneTBB implementation in open source.

Notices and Disclaimers

Intel technologies may require enabled hardware, software or service activation.

No product or component can be absolutely secure.

Your costs and results may vary.

© Intel Corporation. Intel, the Intel logo, and other Intel marks are trademarks of Intel Corporation or its subsidiaries. Other names and brands may be claimed as the property of others.

No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document.

The products described may contain design defects or errors known as errata which ay cause the product to deviate from published specifications. Current characterized errata are available on request.

Intel disclaims all express and implied warranties, including without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement, as well as any warranty arising from course of performance, course of dealing, or usage in trade.