Getting Started

Boost.Int256 is header-only. The core type and functions have no required dependencies, so in most cases it is enough to add the library’s include directory to your compiler’s search path and include the umbrella header:

#include <boost/int256.hpp>

The umbrella header pulls in the type and every feature that has no external dependency. The optional integration headers (charconv.hpp, random.hpp, and the {fmt} support in fmt_format.hpp) are not included by the umbrella and must be included explicitly. See File Structure for the full header list.

B2

Run the following commands to clone the latest version of Boost, prepare the Boost.Build system, and build with C++14 as the default standard:

git clone https://github.com/boostorg/boost
cd boost
git submodule update --init
./bootstrap
./b2 cxxstd=14

To install the headers system-wide, run:

sudo ./b2 install cxxstd=14

The value of cxxstd must be at least 14. See the b2 documentation under cxxstd for all valid values.

CMake

Boost.Int256 ships a CMake package and the Boost::int256 target. When building against a Boost tree that contains this library, request it and link the interface target:

cmake .. -DBOOST_INCLUDE_LIBRARIES="int256"
target_link_libraries(my_target PRIVATE Boost::int256)

The library can also be consumed on its own with FetchContent:

include(FetchContent)
FetchContent_Declare(
    int256
    GIT_REPOSITORY https://github.com/cppalliance/int256
    GIT_TAG        develop
)
FetchContent_MakeAvailable(int256)

target_link_libraries(my_target PRIVATE Boost::int256)

vcpkg

The repository contains a port under ports/int256, so the library can be consumed as an overlay port:

vcpkg install int256 --overlay-ports=/path/to/int256/ports

C++20 Module

When compiling with C++20 or newer, the library can be consumed as a named module instead of via header inclusion:

import boost.int256;

Building the module requires defining BOOST_INT256_BUILD_MODULE and compiling module/int256.cppm with your toolchain’s module support. See Configuration Macros for details.

CUDA Support

The library type and many of the functions can run on both host and device under CUDA. Compile with a CUDA-aware toolchain and define BOOST_INT256_ENABLE_CUDA. Functions carrying BOOST_INT256_HOST_DEVICE in their signature run on both host and device; all others run on host only. See Configuration Macros.

SYCL Support

The library type and many of the functions can also run on the device under SYCL (for example Intel oneAPI icpx -fsycl). SYCL device support is opt-in: include <sycl/sycl.hpp> before any Boost.Int256 header and define BOOST_INT256_ENABLE_SYCL. Functions carrying BOOST_INT256_HOST_DEVICE in their signature run on both host and device; all others run on host only. The boost::charconv::to_chars / from_chars overloads from <boost/int256/charconv.hpp> also run on the SYCL device (Boost.Charconv provides SYCL support, and defining BOOST_INT256_ENABLE_SYCL enables it automatically). See Configuration Macros.

Dependencies

The core library (everything included by <boost/int256.hpp>) has no required dependencies and needs only a conforming C++14 compiler. Nothing in include/boost/int256/ includes a header from another Boost library except in the two optional integrations below, where the include is guarded by __has_include. The optional integration headers depend on the following, and are only usable when those components are available:

Hello World

Nothing beyond the include path is required to start using the type. This program adds two values whose sum does not fit in 128 bits, and prints the result:

Example 1. This example demonstrates including the library and printing a value that no built-in integer type can hold.
// Copyright 2026 Matt Borland
// Distributed under the Boost Software License, Version 1.0.
// https://www.boost.org/LICENSE_1_0.txt

#include <boost/int256.hpp>
#include <iostream>

int main()
{
    // 2^128 is one past the largest value a 128-bit integer can hold
    const boost::int256::uint256 x {boost::int256::uint256{1} << 128U};
    const boost::int256::uint256 y {42};

    std::cout << x << " + " << y << " = " << x + y << std::endl;

    return 0;
}

Output:

340282366920938463463374607431768211456 + 42 = 340282366920938463463374607431768211498

Because the library is header-only, a single command compiles and runs it. Substitute the path to your Boost installation for /path/to/boost:

Linux
g++ -std=c++14 -I /path/to/boost hello_world.cpp -o hello_world && ./hello_world
macOS
clang++ -std=c++14 -I /path/to/boost hello_world.cpp -o hello_world && ./hello_world
Windows
cl /EHsc /std:c++14 /I C:\path\to\boost hello_world.cpp && hello_world.exe
Edit this Page