# Halide

**Repository Path**: mirrors_trending/Halide

## Basic Information

- **Project Name**: Halide
- **Description**: a language for fast, portable data-parallel computation
- **Primary Language**: C++
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2020-08-13
- **Last Updated**: 2026-11-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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](#building-halide).

# 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:

```shell
$ 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][halide-pypi] as a
development version. If you use [uv](https://docs.astral.sh/uv/), you can pin
the nightly Halide in a project like so:

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

Or install directly with `pip`:

```shell
$ 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](https://pypi.halide-lang.org/simple/halide-bin/) or the public
[PyPI index](https://pypi.org/simple/halide-bin/). Python wheel files are just
standard zip files with a `.whl` extension.

## Homebrew

Alternatively, if you use macOS, you can install Halide via
[Homebrew](https://brew.sh/) like so:

```
$ brew install halide
```

## Vcpkg

If you use [vcpkg](https://github.com/microsoft/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](https://github.com/halide/Halide/issues/4660). 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 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][halide-pypi]. This is the easiest way to get a suitable LLVM on
any platform. From the Halide source tree, install with
[uv](https://docs.astral.sh/uv/):

```shell
$ 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](https://brew.sh) is also a good option:
`brew install llvm`. On Debian flavors of Linux, the
[LLVM APT repo](https://apt.llvm.org) 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:

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

(These instructions use LLVM 22.1.8. For current trunk, use `main` instead.)

Then build it like so:

```shell
$ 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](#acquiring-llvm), change directory to the Halide
repository and run:

```shell
$ 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](https://brew.sh/) on macOS, you can use the provided CMake
preset:

```shell
$ 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](https://github.com/Microsoft/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](https://learn.microsoft.com/en-us/vcpkg/concepts/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](#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.

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

> [!WARNING] Building LLVM from source requires significant time, disk space,
> and RAM. Prefer the pre-built `halide-llvm` binaries (see
> [Acquiring LLVM](#acquiring-llvm)) unless you need a custom configuration.

First, download LLVM's sources (these instructions use the 22.1.8 release).

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

As above, run `vcvarsall.bat` to pick between x86 and x64. Then configure LLVM
with the following command (for 32-bit, set `-DLLVM_BUILD_32_BITS=ON` instead):

```
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
```

**MSBuild:** If you want to build LLVM with MSBuild instead of Ninja, use
`-G "Visual Studio 17 2022" -Thost=x64 -A x64` or
`-G "Visual Studio 17 2022" -Thost=x64 -A Win32` in place of `-G Ninja`.

Finally, run the build and install to a local directory:

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

You can substitute `Debug` for `Release` in the above `cmake` commands if you
want a debug build.

To use this with Halide, but still allow vcpkg to manage other dependencies,
point CMake to your LLVM with `-DHalide_LLVM_ROOT=D:/llvm-install`. The overlay
ports in `vcpkg-configuration.json` automatically prevent vcpkg from trying to
build its own LLVM.

</details>

## 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:

```shell
$ 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:

```shell
$ 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](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](doc/GeneratorCache.md).

# Further references

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

| Document                                      | Description                                                               |
| --------------------------------------------- | ------------------------------------------------------------------------- |
| [CMake build](doc/BuildingHalideWithCMake.md) | How to configure and build Halide using CMake.                            |
| [CMake package](doc/HalideCMakePackage.md)    | How to use the Halide CMake package to build your code.                   |
| [Generator cache](doc/GeneratorCache.md)      | How to speed up rebuilds with the opt-in generator compile cache.         |
| [Hexagon](doc/Hexagon.md)                     | How to use the Hexagon backend.                                           |
| [Python](doc/Python.md)                       | Documentation for the Python bindings.                                    |
| [RunGen](doc/RunGen.md)                       | How to use the RunGen interface to run and benchmark arbitrary pipelines. |
| [Vulkan](doc/Vulkan.md)                       | How to use the Halide Vulkan backend (BETA)                               |
| [WebAssembly](doc/WebAssembly.md)             | How to use the WebAssembly backend and how to use V8 in place of wabt.    |
| [WebGPU](doc/WebGPU.md)                       | How to run WebGPU pipelines (BETA)                                        |

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

| Document                                 | Description                                                                                                   |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| [CMake developer](doc/CodeStyleCMake.md) | Guidelines for authoring new CMake code.                                                                      |
| [FuzzTesting](doc/FuzzTesting.md)        | Information about fuzz testing the Halide compiler (rather than pipelines). Intended for internal developers. |
| [Testing](doc/Testing.md)                | Information about our test organization and debugging tips. Intended for internal developers.                 |

[buildinghalidewithcmake.md]: doc/BuildingHalideWithCMake.md
[halide-pypi]: https://pypi.halide-lang.org/simple