qoi

What it is and what it does

QOI is a Python wrapper around the Quite OK Image format, a lossless image codec designed for speed. It reads and writes images as numpy arrays, making it a natural fit for computer-vision and scientific-computing workflows. The package depends only on numpy and compiles to platform-specific wheels, avoiding build friction on most systems.

The format trades some compression efficiency for encoding and decoding speed: lossless QOI is typically 4–20x faster to encode and 1.5–6x faster to decode than PNG, though file sizes are slightly larger. The package also supports a lossy mode via downscaling, which can achieve JPEG-like compression ratios at 5–10x faster encode and 7–8x faster decode speeds. Multi-threaded encoding and decoding are supported without GIL contention, making it suitable for batch processing and high-throughput image pipelines.

Use it for:

• Real-time image capture and storage in computer-vision applications where encoding speed matters more than compression ratio.
• Batch processing large image datasets where lossless fidelity is required but PNG is too slow.
• High-throughput image pipelines using thread pools to encode or decode many images concurrently.
• Lossy image compression for scenarios where visual quality (SSIM ~0.94) is acceptable and speed is critical.
• Intermediate image format in machine-learning training loops where numpy arrays are already in memory.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Python wrapper for the QOI (Quite OK Image) lossless image format that encodes and decodes images as numpy arrays, offering faster compression and decompression than PNG with comparable file sizes.

Yes, if you work with numpy arrays and need faster lossless image I/O than PNG. The package is stable, well-maintained, has no security issues, and installs easily on modern Python. Skip it if compression ratio is your primary concern or if you need formats other than lossless/lossy RGB.

Install

qoi on PyPI

pip install qoi

uv add qoi

poetry add qoi

Installing qoi

Before you install

Prebuilt wheels available for modern Python versions (3.10–3.13) across macOS, Linux, and Windows, reducing compile friction. Package is aging (564 days since last release) but remains actively maintained; no known security issues.

License in practice

MIT license permits unrestricted use, modification, and distribution in both open-source and proprietary projects with minimal obligations.

Quickstart

import numpy as np
import qoi

rgb = np.random.randint(0, 255, size=(224, 244, 3), dtype=np.uint8)
qoi.write('/tmp/img.qoi', rgb)
rgb_read = qoi.read('/tmp/img.qoi')

Requires numpy; image data must be a numpy array in HWC (height, width, channel) ordering.

Verify before relying

• Whether the 10x encoding and 5x decoding speedups over PNG hold consistently across different image types and sizes in real-world workflows.
• Performance characteristics of the lossy mode (downscaling trick) on typical computer-vision pipelines.
• GIL-free multithreading behavior and scalability limits with concurrent.futures or similar patterns.

Package facts

Evidence: qoi-0.7.2-cp310-cp310-macosx_10_9_x86_64.whl; qoi-0.7.2-cp310-cp310-macosx_11_0_arm64.whl; qoi-0.7.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; qoi-0.7.2-cp310-cp310-win32.whl; qoi-0.7.2-cp310-cp310-win_amd64.whl; qoi-0.7.2-cp311-cp311-macosx_10_9_x86_64.whl; qoi-0.7.2-cp311-cp311-macosx_11_0_arm64.whl; qoi-0.7.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; qoi-0.7.2-cp311-cp311-win32.whl; qoi-0.7.2-cp311-cp311-win_amd64.whl; qoi-0.7.2-cp312-cp312-macosx_10_13_x86_64.whl; qoi-0.7.2-cp312-cp312-macosx_11_0_arm64.whl; qoi-0.7.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; qoi-0.7.2-cp312-cp312-win32.whl; qoi-0.7.2-cp312-cp312-win_amd64.whl; qoi-0.7.2-cp313-cp313-macosx_10_13_x86_64.whl; qoi-0.7.2-cp313-cp313-macosx_11_0_arm64.whl; qoi-0.7.2-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; qoi-0.7.2-cp313-cp313-win32.whl; qoi-0.7.2-cp313-cp313-win_amd64.whl

Keywords: qoi

Tags

More Image Processing packages