{"id":21843,"library":"qoi","title":"QOI - Quite OK Image format encoder/decoder","description":"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.","status":"active","version":"0.7.2","language":"python","source_language":"en","source_url":"https://github.com/kodonnell/qoi","tags":["image","codec","qoi","decoder","encoder"],"install":[{"cmd":"pip install qoi","lang":"bash","label":"pip install"}],"dependencies":[{"reason":"Required for image data handling","package":"numpy","optional":false}],"imports":[{"note":"QOI is a module, not a class; use module-level functions write()/read()","wrong":"from qoi import QOI","symbol":"QOI","correct":"import qoi"},{"wrong":"from qoi import read","symbol":"read","correct":"qoi.read('image.qoi')"},{"wrong":"from qoi import write","symbol":"write","correct":"qoi.write('output.qoi', img)"}],"quickstart":{"code":"import qoi\nimport numpy as np\n# Encode a numpy array (HWC uint8) to QOI\nimg = np.random.randint(0, 256, (10, 10, 3), dtype=np.uint8)\nwith open('test.qoi', 'wb') as f:\n    f.write(qoi.encode(img))\n# Decode\nwith open('test.qoi', 'rb') as f:\n    decoded = qoi.decode(f.read())\nprint(decoded.shape)","lang":"python","description":"Encode and decode a QOI image using numpy arrays."},"warnings":[{"fix":"Use qoi.encode(img) to get bytes, qoi.decode(data) to decode bytes.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Update to use qoi.write() and qoi.read() directly (or qoi.encode()/decode() for bytes).","message":"Before v0.7.0, the API used qoi.QOI.write() and qoi.QOI.read() class methods. These are removed in v0.7.0+.","severity":"breaking","affected_versions":"< 0.7.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Use qoi.encode(img) to get bytes, then write to file, or use qoi.write(filepath, img) (if using v0.7+).","message":"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.","severity":"deprecated","affected_versions":"0.6.x"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Use module-level functions: qoi.write() or qoi.read().","cause":"Trying to access a class that was removed in v0.7.0.","error":"AttributeError: module 'qoi' has no attribute 'QOI'"},{"fix":"Verify the file is indeed a QOI image. Check first 4 bytes are b'qoif'.","cause":"Trying to decode data that is not valid QOI format (e.g., missing magic bytes or corrupted).","error":"ValueError: Invalid QOI file"},{"fix":"Cast to uint8: img = img.astype(np.uint8).","cause":"Passing a float array or array with wrong dtype to encode().","error":"TypeError: expected numpy array of dtype uint8"},{"fix":"Convert to RGB by duplicating channel or use a format that supports single channel.","cause":"Input array has 1 or 2 channels (grayscale or RG not supported).","error":"ValueError: Image must have 3 or 4 channels"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}