pillow-rs

pillow-rs is a Rust image-processing library with Python and WebAssembly bindings. It follows Pillow's public behavior through a manifest-driven, input-only parity suite. The current source release is version 0.1.3; compatibility is measured per operation and backend rather than advertised as a complete Pillow replacement.

Current status

The active contract is defined by pillow-rs/tests/fixtures/manifest.yaml (migration-parity/manifest@2). The last complete all-backend campaign selected 11,345 public input workflows and recorded exact terminal output comparisons across the available CPU, SIMD, GPU, Node WASM, and browser WASM lanes. The GPU lane recorded 7,090 native dispatches and 137 explicitly classified host controls; those controls remain visible as backend coverage gaps. Benchmark budget acceptance remains open as described in docs/benchmark-backend-pending-2026-09-03.md.

Version 0.1.2 added three native-font boundary cases. Python 3.10, Python 3.12, Node, and browser WASM each passed 11,348/11,348 comparisons in the 0.1.2 main CI run. Changed-line evidence is recorded in docs/COVERAGE.md, and alpha publication gates are defined in docs/REGISTRY_RELEASE_MATRIX.md.

Version 0.1.3 fixes the npm publishing job's Node cache configuration. The 0.1.2 Cargo and PyPI uploads succeeded through OIDC; its npm job stopped before authentication. Runtime behavior and the parity corpus are unchanged in 0.1.3.

These figures are measured evidence from named runs, not a promise that every Pillow API, platform, or GPU adapter is supported.

Packages

The Python wheel uses the abi3-py38 boundary and declares requires-python >=3.8. The parity oracle is Pillow 12.2.0, which requires Python 3.10 or newer, so CI parity runs use Python 3.10 and 3.12. The WASM CI lane uses Node 22.14.0 with npm 11.5.1.

Quick start from a checkout

Use an isolated Python 3.10+ environment for the parity tools:

make setup-venv PYTHON=python3.12
make build
python -c "from PIL import Image; print(Image.new('RGB', (10, 10)))"

The Python package uses Pillow's normal PIL import path. make build is a local replacement install; for parity work, use make build-parity so the checkout facade is available on PYTHONPATH while the separately installed Pillow oracle remains intact.

Migrating from RSPIL

Replace the old package import directly:

from PIL import Image

The public PIL modules are backed by the Rust extension. pillow_rs is an internal binding namespace, and RSPIL remains only as a deprecated import bridge for older applications.

Build the WASM package and run its package check with:

make build-wasm-release
cd pillow-rs-js && npm run test:package

Published registry artifacts are not implied by this source checkout. Use the release checklist before installing from or publishing to PyPI, npm, or crates.io.

API and parity

The manifest currently declares 24 public surfaces, 209 operations, 1,801 requirements, 11,348 parity inputs, 24 coverage plans, and 744 standard benchmark workloads. These are declared/indexed counts; live results are kept separately in build/migration-parity/.

Every active parity case contains only public stimulus. Pillow produces the oracle result at run time, and the Rust target is compared with the same input. Coverage selectors and benchmark workloads reference those cases without embedding expected output bytes or hashes.

Regenerate and validate the input contract with:

make migration-parity-inputs
make migration-parity-inputs-check
make migration-parity-fixtures-check

Test and verification commands

The root Makefile is the maintained command interface:

make fmt
make clippy
make migration-parity-test
make migration-parity-test-all-backends
make migration-parity-coverage
make test

make test runs the shared target lanes, JS/WASM lanes, reverse Pillow source coverage, and the ordered missing-feature report. GPU and browser capability limitations are recorded in the result artifact. They are not converted into passing output.

For one case, use make migration-parity-case MIGRATION_PARITY_CASE=<case-id>. Use the same case ID with the coverage and all-backend variables when debugging a first divergence.

Benchmarking

The benchmark inputs and repeat policy are documented in docs/BENCHMARKING.md. Run the quick smoke cohort with:

MIGRATION_BENCHMARK_PROFILE=quick make migration-parity-benchmark
make migration-parity-pipeline-report

Run the complete standard workload set with MIGRATION_BENCHMARK_PROFILE=standard make migration-parity-benchmark. A timing number is publishable only when the workload passed its correctness gate and the manifest, input, runtime, and backend identities match the comparison. Use MIGRATION_BENCHMARK_PROFILE=release make migration-parity-benchmark for the fixed 11-workload release acceptance cohort. BENCHMARKS.md is a landing page; the JSON result is the evidence record.

Architecture

pillow-rs/       pure Rust image model, operations, pipeline, and backends
pillow-rs-py/    thin PyO3 boundary and Python compatibility modules
pillow-rs-js/    thin wasm-bindgen boundary and Node/browser adapters
scripts/         manifest generators, parity runners, validators, and reports

Runtime image logic lives in the Rust core. Bindings convert host values and delegate to it. The compute registry can route a pipeline through CPU, SIMD, or GPU; unsupported or unproven GPU work keeps an explicit host-control record and follows the configured fallback policy.

Documentation map

Older dated reports, CODEBASE_AUDIT.md, SYSTEMIC_FIXES.md, and docs/superpowers/ are historical references. The retired fixture and oracle trees are under deprecated/ with an explicit migration map.

Contributing

Before opening a change, read CONTRIBUTING.md and the documentation checklist. New operations require a manifest entry, input-only parity and coverage cases, and measured coverage. Fixes must preserve failing cases and thresholds until the implementation is correct.

License and attribution

pillow-rs is licensed under the MIT-CMU License. It targets the public behavior of Pillow, whose license and attribution remain in LICENSE. The pinned fontdone checkout and image-slash-star dependency retain their own licenses and notices.