QOI - Quite OK Image format encoder/decoder

0.7.2 verified Mon Apr 27 auth: no python

A Python wrapper around the QOI (Quite OK Image format) reference implementation by phoboslab. Supports encoding and decoding QOI images from numpy arrays or raw bytes. Current version 0.7.2 (stable), release cadence: sporadic.

pip install qoi

Common errors

error AttributeError: module 'qoi' has no attribute 'QOI' ↓

cause Trying to access a class that was removed in v0.7.0.

fix

Use module-level functions: qoi.write() or qoi.read().

error ValueError: Invalid QOI file ↓

cause Trying to decode data that is not valid QOI format (e.g., missing magic bytes or corrupted).

fix

Verify the file is indeed a QOI image. Check first 4 bytes are b'qoif'.

error TypeError: expected numpy array of dtype uint8 ↓

cause Passing a float array or array with wrong dtype to encode().

fix

Cast to uint8: img = img.astype(np.uint8).

error ValueError: Image must have 3 or 4 channels ↓

cause Input array has 1 or 2 channels (grayscale or RG not supported).

fix

Convert to RGB by duplicating channel or use a format that supports single channel.

Warnings

gotcha qoi.write() and qoi.read() operate on file paths, not bytes. For in-memory operations use qoi.encode() and qoi.decode() which work on bytes. ↓

fix Use qoi.encode(img) to get bytes, qoi.decode(data) to decode bytes.

breaking Before v0.7.0, the API used qoi.QOI.write() and qoi.QOI.read() class methods. These are removed in v0.7.0+. ↓

fix Update to use qoi.write() and qoi.read() directly (or qoi.encode()/decode() for bytes).

gotcha qoi.encode() requires a uint8 numpy array with shape (height, width, channels) where channels is 3 (RGB) or 4 (RGBA). Other dtypes or channel counts will raise ValueError. ↓

fix Ensure image is uint8 and 3 or 4 channels: img = img.astype(np.uint8) and if 2D reshape to (h,w,1) not supported.

deprecated Passing numpy arrays as arguments to write() is deprecated in v0.6.x and removed in v0.7.0. Use encode() for bytes or write() with file path. ↓

fix Use qoi.encode(img) to get bytes, then write to file, or use qoi.write(filepath, img) (if using v0.7+).

Imports

QOI
wrong
```
from qoi import QOI
```
correct
```
import qoi
```
QOI is a module, not a class; use module-level functions write()/read()

read

wrong

from qoi import read

correct

qoi.read('image.qoi')

write

wrong

from qoi import write

correct

qoi.write('output.qoi', img)

Quickstart

Encode and decode a QOI image using numpy arrays.

import qoi
import numpy as np
# Encode a numpy array (HWC uint8) to QOI
img = np.random.randint(0, 256, (10, 10, 3), dtype=np.uint8)
with open('test.qoi', 'wb') as f:
    f.write(qoi.encode(img))
# Decode
with open('test.qoi', 'rb') as f:
    decoded = qoi.decode(f.read())
print(decoded.shape)