Halide

Halide is a programming language designed to make it easier to write high-performance image and array processing code on modern machines. Halide currently targets:

• CPU architectures: X86, ARM, Hexagon, PowerPC, RISC-V, WebAssembly
• Operating systems: Linux, Windows, macOS, Android, iOS, Qualcomm QuRT
• GPU Compute APIs: CUDA, OpenCL, Apple Metal, Microsoft Direct X 12, Vulkan

Rather than being a standalone programming language, Halide is embedded in C++. This means you write C++ code that builds an in-memory representation of a Halide pipeline using Halide's C++ API. You can then compile this representation to an object file, or JIT-compile it and run it in the same process. Halide also provides a Python binding that provides full support for writing Halide embedded in Python without C++.

Halide requires C++17 (or later) to use.

For more detail about what Halide is, see https://halide-lang.org.

For API documentation see https://halide-lang.org/docs.

For some example code, read through the tutorials online at https://halide-lang.org/tutorials. The corresponding code is in the tutorials/ directory. Larger examples are in the apps/ directory.

If you've acquired a full source distribution and want to build Halide, see the notes below.

Getting Halide

Pip

We provide binary wheels on PyPI. Halide provides bindings for C++ and Python. Even if you only intend to use Halide from C++, pip may be the easiest way to get a binary build of Halide.

Full releases may be installed with pip like so:

$ pip install halide

Every commit to main is published to our [package index][halide-pypi] as a development version. If you use uv, you can pin the nightly Halide in a project like so:

$ uv add halide --prerelease=allow --index https://pypi.halide-lang.org/simple

Or install directly with pip:

$ pip install halide --pre --extra-index-url https://pypi.halide-lang.org/simple

Currently, we provide wheels for: Windows x86-64, macOS x86-64, macOS arm64, and Linux x86-64. The Linux wheels are built for manylinux_2_28, which makes them broadly compatible (Debian 10, Ubuntu 18.10, Fedora 29).

For C++ usage of the pip package: On Linux and macOS, CMake's find_package command should find Halide as long as you're in the same virtual environment you installed it in. On Windows, you will need to add the virtual environment root directory to CMAKE_PREFIX_PATH. This can be done by running set CMAKE_PREFIX_PATH=%VIRTUAL_ENV% in cmd.

Other build systems can find the Halide root path by running python -c "import halide; print(halide.install_dir())".

Homebrew

Alternatively, if you use macOS, you can install Halide via Homebrew like so:

$ brew install halide

Binary tarballs

The latest version of Halide can always be found on GitHub at https://github.com/halide/Halide/releases

We provide binary releases for many popular platforms and architectures, including 32/64-bit x86 Windows, 64-bit x86/ARM macOS, and 32/64-bit x86/ARM Ubuntu Linux.

The Linux tarballs are built on a recent Ubuntu LTS; if your distribution is too old, it might not have the requisite glibc. The pip wheels are built for manylinux_2_28 and are more broadly compatible.

Vcpkg

If you use vcpkg to manage dependencies, you can install Halide via:

$ vcpkg install halide:x64-windows # or x64-linux/x64-osx

One caveat: vcpkg installs only the minimum Halide backends required to compile code for the active platform. If you want to include all the backends, you should install halide[target-all]:x64-windows instead.

Other package managers

We are interested in bringing Halide to other popular package managers and Linux distribution repositories! We track the status of various distributions of Halide in this GitHub issue. If you have experience publishing packages we would be happy to work with you!

Building Halide

Platform Support

There are two sets of platform requirements relevant to Halide: those required to run the compiler library in either JIT or AOT mode, and those required to run the binary outputs of the AOT compiler.

These are the tested host toolchain and platform combinations for building and running the Halide compiler library.

| Compiler | Version | OS | Architectures | | ---------- | ------------ | ---------------------- | ------------- | | GCC | 9.5 | Ubuntu Linux 20.04 LTS | x86, x64 | | GCC | 11.4 | Ubuntu Linux 22.04 LTS | ARM32, ARM64 | | MSVC | 2022 (19.37) | Windows 11 (22631) | x86, x64 | | AppleClang | 15.0.0 | macOS 14.4.1 | x64 | | AppleClang | 14.0.0 | macOS 14.6 | ARM64 |

Some users have successfully built Halide for Linux using Clang 9.0.0+, for Windows using ClangCL 11.0.0+, and for Windows ARM64 by cross-compiling with MSVC. We do not actively test these scenarios, however, so your mileage may vary.

Beyond these, we are willing to support (by accepting PRs for) platform and toolchain combinations that still receive active, first-party, public support from their original vendors. For instance, at time of writing, this excludes Windows 7 and includes Ubuntu 18.04 LTS.

Compiled AOT pipelines are expected to have much broader platform support. The binaries use the C ABI, and we expect any compliant C compiler to be able to use the generated headers correctly. The C++ bindings currently require C++17. If you discover a compatibility problem with a generated pipeline, please open an issue.

Acquiring LLVM

At any point in time, building Halide requires either the latest stable version of LLVM, the previous stable version of LLVM, or trunk. At the time of writing, this means versions 23, 22, and 21 are supported, but 20 is not.

We publish the LLVM builds we use in CI as Python packages on our [package index][halide-pypi]. This is the easiest way to get a suitable LLVM on any platform. From the Halide source tree, install with uv:

$ uv sync --group ci-llvm-22 --no-install-project
$ export Halide_LLVM_ROOT=$(halide-llvm --prefix)

Replace 22 with the desired LLVM major version (21, 22, 23, or main). Binary wheels are available for Linux (x86-64, x86-32, AArch64, ARMv7), macOS (x86-64, ARM64), and Windows (x86-64, x86-32).

On macOS, Homebrew is also a good option: brew install llvm. On Debian flavors of Linux, the LLVM APT repo works well; use the provided installation script.

<details> <summary>Building LLVM from source (advanced)</summary>

[!WARNING] Building LLVM from source requires significant time, disk space, and RAM. Prefer the pre-built binaries above unless you need a custom configuration.

First check it out from GitHub:

$ git clone --depth 1 --branch llvmorg-21.1.8 https://github.com/llvm/llvm-project.git

(LLVM 21.1.8 is the most recent released LLVM at the time of writing. For current trunk, use main instead)

Then build it like so:

$ cmake -G Ninja -S llvm-project/llvm -B build \
        -DCMAKE_BUILD_TYPE=Release \
        -DLLVM_ENABLE_PROJECTS="clang;lld;clang-tools-extra" \
        -DLLVM_ENABLE_RUNTIMES=compiler-rt \
        -DLLVM_TARGETS_TO_BUILD="WebAssembly;X86;AArch64;ARM;Hexagon;NVPTX;PowerPC;RISCV" \
        -DLLVM_ENABLE_ASSERTIONS=ON \
        -DLLVM_ENABLE_EH=ON \
        -DLLVM_ENABLE_RTTI=ON \
        -DLLVM_ENABLE_HTTPLIB=OFF \
        -DLLVM_ENABLE_LIBEDIT=OFF \
        -DLLVM_ENABLE_LIBXML2=OFF \
        -DLLVM_ENABLE_TERMINFO=OFF \
        -DLLVM_ENABLE_ZLIB=OFF \
        -DLLVM_ENABLE_ZSTD=OFF \
        -DLLVM_BUILD_32_BITS=OFF
$ cmake --build build
$ cmake --install build --prefix llvm-install

This will produce a working LLVM installation in $PWD/llvm-install. We refer to this path as LLVM_ROOT later. Do not confuse this installation tree with the build tree!

LLVM takes a long time to build, so the above command uses Ninja to maximize parallelism. If you choose to omit -G Ninja, Makefiles will be generated instead. In this case, enable parallelism with cmake --build build -j NNN where NNN is the number of parallel jobs, i.e. the number of CPUs you have.

Note that you must add clang and lld to LLVM_ENABLE_PROJECTS and WebAssembly and X86 must be included in LLVM_TARGETS_TO_BUILD. LLVM_ENABLE_RUNTIMES=compiler-rt is only required to build the fuzz tests, and clang-tools-extra is only necessary if you plan to contribute code to Halide (so that you can run clang-tidy on your pull requests). You can disable exception handling (EH) and RTTI if you don't want the Python bindings. We recommend enabling the full set to simplify builds during development.

</details>

Building Halide with CMake

This is discussed in greater detail in [BuildingHalideWithCMake.md]. CMake version 3.28+ is required to build Halide.

MacOS and Linux

After acquiring LLVM, change directory to the Halide repository and run:

$ cmake -G Ninja -S . -B build -DCMAKE_BUILD_TYPE=Release -DHalide_LLVM_ROOT=$LLVM_ROOT
$ cmake --build build

Setting -DHalide_LLVM_ROOT is not required if you have a suitable system-wide version installed. However, if you have multiple LLVMs installed, it can pick between them. Do not use a relative path for Halide_LLVM_ROOT. It can cause problems on some systems.

If you use Homebrew on macOS, you can use the provided CMake preset:

$ cmake --preset=macOS -S . -B build
$ cmake --build build

This automatically finds LLVM from Homebrew's install path.

Windows

We suggest building with Visual Studio 2022. Your mileage may vary with earlier versions