pillow-rs

Rust image processing with a familiar Python PIL interface and one WebAssembly package for Node.js and browsers.

Documentation · API support · Benchmarks · Rust guide

Current candidate: 12.2.0-alpha.1 (unreleased). Cargo, npm, Python, and this documentation use the same declared version. The base version tracks the targeted Pillow release; alpha.1 identifies this project's first candidate for that target. Matching version numbers do not imply complete compatibility. Read maturity and limitations before replacing Pillow in an application.

This candidate removes deprecated Rust interfaces and the former Python import bridge. See the migration guide and release checklist. Published-release evidence retains the version and revision actually measured.

Choose your package

The registry commands below apply after this candidate is published. To try it now, build from source.

The release workflow builds Python wheels for Linux x86-64 (glibc 2.28+), macOS ARM64, and Windows x86-64. Other platforms may build from the source distribution; they are outside the wheel matrix. Rust source builds use Rust 1.96.1. See installation for runtime requirements.

Make your first image

Use a fresh Python environment. Both Pillow and pillow-rs provide PIL, so install them in separate environments.

python3 -m venv .venv
.venv/bin/python -m pip install pillow-rs==12.2.0-alpha.1

On Windows, use .venv\Scripts\python.exe instead of .venv/bin/python.

from io import BytesIO
from PIL import Image, ImageOps

image = Image.new("RGB", (3, 2), (255, 12, 34))
image = ImageOps.mirror(image).resize((6, 4))
output = BytesIO()
image.save(output, format="PNG")
assert image.size == (6, 4)
assert output.getvalue().startswith(b"\x89PNG\r\n\x1a\n")

Continue with Python recipes, JavaScript and browser integration, or Rust integration.

What to expect

• Creation, transformations, drawing, filters, color, and font operations have a fixed public contract. The API inventory identifies every selected path and its input cases.
• Python uses familiar PIL imports. JavaScript exposes an explicitly initialized WASM API; it does not reproduce Python syntax or objects.
• The Rust core uses image-slash-star for codecs and fontdone for fonts.
• CPU, SIMD, and optional GPU execution have different measured support. A passing comparison does not by itself establish native GPU execution.
• This alpha does not promise complete Pillow replacement, hardened decoding of arbitrary hostile inputs, or a stable API.

Performance you can inspect

The benchmark site shows workload timings, sample counts, spread, correctness gates, and actual backends. Historical results retain their source revision. Missing measurements remain unavailable. There is no single project-wide speedup claim.

Read the measurement protocol to reproduce a run. Benchmark budget acceptance is separate from correctness and publication.

Contribute

Bug reports, small reproductions, documentation improvements, and input-driven parity fixes are welcome. Start with CONTRIBUTING.md.

make help
make setup-venv PYTHON=python3.12
make build-parity
make migration-parity-test

For documentation only, use make docs-setup, make docs-build, and make docs-serve. Each repository builds and publishes its own GitHub Pages site. The command reference explains side effects and scope.

Project information

• Support and private security reporting
• Code of conduct
• Changelog and release process
• Architecture and coverage evidence

The project is distributed under the MIT-CMU License. Dependencies and fixture assets retain their own licenses and notices.

Acknowledgements

Thank you to Puhu for the Rust/Python image processing work that informed the early exploration of this project, and to Pillow and its contributors for the image library, public API, and reference behavior on which the compatibility work depends.