---
id: qoi
version: "0.7.2"
license: MIT
license_treatment: permissive
maintenance: aging
---

# qoi — A simpler wrapper around qoi (https://github.com/phoboslab/qoi)

License: permissive · Maintenance: aging · Downloads: 212.0K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: aging
- Downloads: 212.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

image compression lossless, qoi image format python, fast image encoding decoding, numpy image codec, png alternative fast, image format wrapper, multithreaded image processing, image-codec, numpy-native, fast-compression

[View on SkillFed](https://skillfed.io/packages/qoi) · [View on PyPI](https://pypi.org/project/qoi/)