Halide

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, FreeBSD, 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 or added to a uv project like so:

$ pip install halide
$ uv add halide

The published Python artifacts are split into three distributions that share the halide import package. The halide distribution provides the compiler Python API and depends on matching versions of halide-bin (the compiler, headers, tools, and CMake package) and halide-runtime (the standalone halide.runtime API). Most users should install only halide; the package manager installs its two dependencies automatically. Deployments that only call precompiled AOT pipelines can instead install halide-runtime, avoiding the compiler and LLVM entirely.

Every commit to main is published to our package index 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())".

Alternative for no-Python Environments

If you cannot use Python tooling (e.g. pip or uv) to download the Halide wheels, you can download them directly from either our nightly index or the public PyPI index. Python wheel files are just standard zip files with a .whl extension.

Homebrew

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

$ brew install halide

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.

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 22, 23, and 24 (trunk) are supported, but 21 is not.

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

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

Replace 22 with the desired LLVM major version (22, 23, or main). The repository root is a uv workspace containing the three Python distributions. --no-install-workspace installs only the development tools and LLVM package needed for a normal CMake build; --frozen uses the committed lockfile without evaluating or building the workspace packages. To build and install all three workspace packages into the uv environment instead, run uv sync --all-packages; this includes a full compiler build. 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.

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

$ 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

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 --preset release -DHalide_LLVM_ROOT=$LLVM_ROOT
$ cmake --build build/release

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
$ cmake --build build/macOS

This automatically finds LLVM from Homebrew’s install path.

Windows

We suggest building with Visual Studio 2022. Your mileage may vary with earlier versions. Be sure to install the “C++ CMake tools for Windows” in the Visual Studio installer. For older versions of Visual Studio, do not install the CMake tools, but instead acquire CMake and Ninja from their respective project websites.

These instructions start from the D: drive. We assume this git repo is cloned to D:\Halide. We also assume that your shell environment is set up correctly. For a 64-bit build, run:

D:\> "C:\Program Files (x86)\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x64

For a 32-bit build, run:

D:\> "C:\Program Files (x86)\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x64_x86

Managing dependencies with vcpkg

The best way to get compatible dependencies on Windows is to use vcpkg. Install it like so:

D:\> git clone https://github.com/Microsoft/vcpkg.git
D:\> cd vcpkg
D:\vcpkg> .\bootstrap-vcpkg.bat -disableMetrics
...
CMake projects should use: "-DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake"

Halide includes a vcpkg-configuration.json that automatically configures overlay ports and overlay triplets. These overlays redirect LLVM and Python to system installations, so vcpkg only builds the smaller dependencies (flatbuffers, wabt, nanobind, etc.). You must have LLVM and Python installed separately (see Acquiring LLVM above).

If CMake does not find your LLVM installation automatically, pass its absolute path as -DHalide_LLVM_ROOT, for example:

D:\Halide> cmake --preset=release-vcpkg -DHalide_LLVM_ROOT=D:/llvm-install

Building Halide

Create a separate build tree and call CMake with vcpkg’s toolchain. This will build in either 32-bit or 64-bit depending on the environment script (vcvars) that was run earlier.

D:\Halide> cmake -G Ninja -S . -B build ^
                 --toolchain D:/vcpkg/scripts/buildsystems/vcpkg.cmake ^
                 -DCMAKE_BUILD_TYPE=Release ^
                 -DVCPKG_MANIFEST_FEATURES=developer

Or use a CMake preset (e.g. for a Visual Studio build):

D:\Halide> cmake --preset=win64  &:: or win32 for 32-bit
D:\Halide> cmake --build build\win64 --config Release

For a Ninja-based build with vcpkg (needs VCPKG_ROOT set in the environment):

D:\Halide> cmake --preset=release-vcpkg
D:\Halide> cmake --build build\release-vcpkg

To run all the tests:

D:\Halide> ctest --test-dir build\release-vcpkg --output-on-failure

Subsets of the tests can be selected with -L and include correctness, generator, and the other directory names under tests/.

To build the apps, you must first install Halide to a local prefix and record that prefix in CMAKE_PREFIX_PATH (or set as -DCMAKE_PREFIX_PATH on the CMake command line):

D:\Halide> cmake --build build\release-vcpkg --target install

By default, this will install to D:\Halide\install\release-vcpkg. You can choose a different install prefix by manually calling cmake --install with --prefix <path>.

Then move to the apps folder:

D:\Halide> cd apps
D:\Halide\apps> cmake --preset=release-vcpkg
D:\Halide\apps> cmake --build --preset=release-vcpkg

These commands configure all apps and resolve the dependencies in apps/vcpkg.json; vcpkg may build both Debug and Release versions of those dependencies. To build a single app without configuring the full apps project, configure from that app’s directory instead. To build just one app in an already-configured apps project, pass its directory name as the build target, for example cmake --build --preset=release-vcpkg --target blur. This builds all targets needed by that app; the app-named target may be an executable or a custom target aggregating several targets.

For example, to build blur standalone with dependencies already installed in the selected vcpkg triplet:

D:\Halide\apps\blur> cmake -G Ninja -S . -B build ^
                          --toolchain D:/vcpkg/scripts/buildsystems/vcpkg.cmake ^
                          -DVCPKG_MANIFEST_MODE=OFF ^
                          -DCMAKE_BUILD_TYPE=Release ^
                          -DHalide_ROOT=D:/Halide/install/release-vcpkg
D:\Halide\apps\blur> cmake --build build

VCPKG_MANIFEST_MODE=OFF makes vcpkg use dependencies already installed for the selected triplet instead of installing all dependencies from apps/vcpkg.json. Install any dependencies required by the chosen app first.

D:\> git clone --depth 1 --branch llvmorg-22.1.8 https://github.com/llvm/llvm-project.git

D:\> 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

D:\> cmake --build build --config Release
D:\> cmake --install build --prefix llvm-install

Building Halide with make

[!WARNING] We do not provide support for the Makefile. Feel free to use it, but if anything goes wrong, switch to the CMake build. Note also that the Makefile cannot build the Python bindings or produce install packages.

TL;DR: Have LLVM 22 (or greater) installed and run make in the root directory of the repository (where this README is).

By default, make will use the llvm-config tool found in the PATH. If you want to use a different LLVM, such as a custom-built one following the instructions above, set the following environment variable:

$ export LLVM_CONFIG="$LLVM_ROOT/bin/llvm-config"

Now you should be able to just run make in the root directory of the Halide source tree. make run_tests will run the JIT test suite, and make test_apps will make sure all the apps compile and run (but won’t check their output).

When building the tests, you can set the AOT compilation target with the HL_TARGET environment variable.

Building Halide out-of-tree with make

If you wish to build Halide in a separate directory, you can do that like so:

$ cd ..
$ mkdir halide_build
$ cd halide_build
$ make -f ../Halide/Makefile

Some useful environment variables

HL_JIT_TARGET=... will set Halide’s JIT compilation target.

HL_DEBUG_CODEGEN=1 will print out pseudocode for what Halide is compiling. Higher numbers will print more detail. The output can be filtered by source location using the grammar verbosity[,filename[:line_low[-line_high]]][@func], with rules separated by ; and OR-ed together (filenames and function names are matched as suffixes). For example, HL_DEBUG_CODEGEN=3,Simplify.cpp:100-180 prints verbosity-3 output only from lines 100–180 of Simplify.cpp. A handful of call sites are also given a stable tag (their second debug() argument, e.g. debug(1, "counterexample")), independent of file/line, selectable via a tag:name rule (e.g. HL_DEBUG_CODEGEN=tag:counterexample, or HL_DEBUG_CODEGEN=tag:counterexample,non-monotonic to select either); a tag rule fires whenever one of its names matches, regardless of verbosity. See doc/Testing.md for more, including the LLDB/GDB debugger helpers. HL_DEBUG_CODEGEN output goes to stderr by default; set HL_DEBUG_CODEGEN_LOG_FILE=<path> to append it to a file instead (the file is never truncated). The values /dev/stdout and /dev/stderr are recognized explicitly and remapped to std::cout/std::cerr on all platforms, including Windows, which has no /dev filesystem to fall back on.

HL_NUM_THREADS=... specifies the number of threads to create for the thread pool. When the async scheduling directive is used, more threads than this number may be required and thus allocated. A maximum of 256 threads is allowed. (By default, the number of cores on the host is used.)

HL_TRACE_FILE=... specifies a binary target file to dump tracing data into (ignored unless at least one trace_ feature is enabled in the target). The output can be parsed programmatically by starting from the code in utils/HalideTraceViz.cpp.

HL_CACHE_DIR=... enables the opt-in generator compile cache, restoring a generator’s previously emitted artifacts instead of recompiling when its inputs are unchanged. See Generator cache.

Further references

We have more documentation in doc/, the following links might be helpful:

The following links are of greater interest to developers wishing to contribute code to Halide: