qoi

library0.7.2pypypi✓ verified 89d ago

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.

data serialization

pip install qoi

github ↗package ↗

INSTALL

IMPORT

SIG · QOI

qoi

datapythonv0.7.2

Install

3.8s avg

Import

284ms

Disk

88MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.7.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

build_error

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.8s · import 0.284s · 87MB

88MB installed

● package 88MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

QOI

✓ import qoi

✗ from qoi import QOI

QOI is a module, not a class; use module-level functions write()/read()

read

✓ qoi.read('image.qoi')

✗ from qoi import read

write

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

✗ from qoi import write

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)

Debug

Known issues

gotchaqoi.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.

affects: all

breakingBefore 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).

affects: < 0.7.0

gotchaqoi.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.

affects: all

deprecatedPassing 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+).

affects: 0.6.x

Errors

Common errors & fixes

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

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

fix

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

ValueError: Invalid QOI file

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'.

TypeError: expected numpy array of dtype uint8

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

fix

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

ValueError: Image must have 3 or 4 channels

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.

Upgrade

Version history

0.7.2latest on PyPI · released Jan 27, 2025

Audit

Dependencies

numpyrequiredRequired for image data handling

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/kodonnell/qoi ↗

packagehttps://pypi.org/project/qoi/ ↗