About Pillow-AllSIMD

Pillow-AllSIMD is Pillow with SIMD kernels: a fork of Pillow-SIMD, which is a fork of Pillow. Everything in these pages about Pillow’s API applies to it unchanged; this page and Fast mode (Pillow-AllSIMD) are its own.

Aim

  • SIMD on every common CPU. Pillow-SIMD targets x86; Pillow-AllSIMD carries its kernels further on x86-64 (SSE4, AVX2, AVX-VNNI) and ports them to arm64 (NEON), with portable C that compilers vectorize elsewhere.

  • Fast by default. Fast mode (Pillow-AllSIMD) uses kernels whose results differ from Pillow’s by a few documented levels at most, the same on every build and architecture.

  • Pillow’s results when asked. In exact mode the operations follow Pillow’s arithmetic, or an integer form of it that rounds differently by one level at most in a few places (resize with 16-bit coefficients, RGB to L with 15-bit ones), and each SIMD kernel is checked against the scalar code on every build.

  • Following Pillow. Each Pillow release is merged, and changes that suit Pillow-SIMD are offered to it.

State

  • Version 13.0.0.post1, on Pillow 13.0.0 (the simd/pillow-13 branch).

  • Beta. On PyPI as a source package, compiled on installation (below).

  • Tested on x86-64 (Intel Core Ultra 9 285H) and arm64 (NVIDIA Jetson Orin): Pillow’s test suite on every build, the SIMD consistency tests, and output hashes per kernel that compare the builds (checks/simd_hashes.py). The portable build also passes the suite on riscv64, ppc64le, s390x, armv7 and 32-bit x86, under QEMU (design/OTHER_ARCHITECTURES.md in the repository).

  • Benchmarks against Pillow, Pillow-SIMD, OpenCV, libvips and ImageMagick, exact and fast mode.

Installing

Pillow-AllSIMD is on PyPI as a source package, which pip compiles on installation, so install the libraries that building Pillow from source needs first. It installs the PIL package, like Pillow: install your other packages first, then uninstall Pillow (or Pillow-SIMD) and install Pillow-AllSIMD, choosing the instruction set with the simd build option:

python3 -m pip uninstall -y pillow pillow-simd
python3 -m pip install -C simd=avx2 pillow-allsimd

Uninstall Pillow before, not after: both own the files in PIL. To rebuild with another simd option, add --no-cache-dir --force-reinstall, or pip reuses the wheel it built first. The development branch installs with "pillow-allsimd @ git+https://github.com/desmoteo/pillow-allsimd@simd/pillow-13".

The simd option takes:

  • auto (the default): SSE4.1 on x86, NEON on arm64, portable C elsewhere.

  • sse4: SSE4.1 (x86 only).

  • avx2: SSE4.1 and AVX2 (x86 only).

  • avxvnni: SSE4.1, AVX2 and AVX-VNNI (x86 only: Intel Alder Lake, Sapphire Rapids and newer, AMD Zen 5); faster integer filters and resize.

  • native: everything the build machine’s CPU supports (-march=native), AVX-512 included in compiler-generated code; the build runs only on similar CPUs.

  • native512: like native, with 512-bit vectors preferred (x86 only).

  • neon: NEON (arm64 only).

  • disable: portable C only, on any architecture.

Don’t pass the instruction set in CFLAGS: setting it replaces Python’s compiler flags, the optimization level included.

What is accelerated

Resampling and reduce, box and Gaussian blur, the unsharp mask, alpha composition and premultiplication, colour conversions (grayscale, RGB and RGBA, CMYK, HSV, YCbCr), kernel and rank filters, rotations, transposes and transforms, colour lookup tables, channel operations, point tables, palette mapping, drawing fills, PNG row filters and pixel packing, each with the instruction sets the readme lists.

Credits

  • PIL, the Python Imaging Library, by Fredrik Lundh and contributors (Secret Labs AB, 1995-2011).

  • Pillow, the friendly PIL fork, by Jeffrey ‘Alex’ Clark and contributors (2010-): the library as a whole, its tests and this documentation.

  • Pillow-SIMD, by Alexander Karpinsky and contributors, supported by Uploadcare, which has run it in production since 2015: the SIMD resampling, blur, filter, conversion and composition kernels for x86 that Pillow-AllSIMD starts from, and the idea of a drop-in SIMD build.

  • Pillow-AllSIMD’s own changes: Matteo Ferrabone and contributors.

To cite Pillow-AllSIMD, use its CITATION.cff, which cites Pillow and Pillow-SIMD too. All four are under the MIT-CMU License (About).

Reporting issues

Bugs that aren’t about the SIMD code or fast mode are Pillow’s: please report them to Pillow, whose fixes reach Pillow-AllSIMD with each merged release. Issues with the SIMD kernels, the builds or fast mode go to Pillow-AllSIMD’s issues.