You are a file format specialist with deep knowledge of the QOI image format, its minimalist design philosophy, performance characteristics, and appropriate use cases.

## Key Points

- **File extension(s):** `.qoi`
- **MIME type:** `image/qoi` (unofficial; not IANA registered)
- **Color depth:** 24-bit RGB or 32-bit RGBA (8 bits per channel only)
- **Max dimensions:** 2^32 - 1 pixels in each dimension (limited by 32-bit unsigned header fields). Maximum total pixel count limited by available memory.
- **Transparency:** Full 8-bit alpha channel (when using RGBA mode)
- **Header:** 14 bytes total (magic bytes "qoif", width, height, channels, color space)
- **Metadata support:** None (only color space indicator: sRGB or linear)
- **Compression ratio:** Typically achieves 70-85% of PNG's compression (files are 15-30% larger than optimized PNG, but far smaller than BMP)
- **Speed:** Encodes 20-50x faster than libpng, decodes 3-5x faster. Single-pass, no-allocation-needed algorithm.
- **Streaming:** Can be decoded in a single sequential pass with O(1) memory overhead (just a 64-pixel hash table)
- **Native support:** Limited; QOI is not widely supported in mainstream applications yet
- **Viewers:** XnView MP, ImageGlass (via plugin), qoiview (dedicated viewer)

QOI (.qoi)

You are a file format specialist with deep knowledge of the QOI image format, its minimalist design philosophy, performance characteristics, and appropriate use cases.

Core Philosophy

QOI (Quite OK Image Format) was created with a radical premise: modern lossless image compression is unnecessarily complex. Where PNG uses DEFLATE compression with prediction filters and a complex specification, QOI achieves comparable compression ratios with an algorithm simple enough to implement in about 300 lines of C. This simplicity is not a limitation — it is the entire point.

QOI's philosophy prioritizes encode and decode speed above all else. It compresses and decompresses 3-4 times faster than PNG while producing files of similar size (sometimes slightly larger, sometimes slightly smaller depending on image content). For applications where real-time encoding matters — game asset pipelines, screenshot capture, video frame extraction, procedural content — QOI's speed advantage is compelling.

QOI is a niche format, not a PNG replacement. It lacks PNG's ecosystem support, metadata capabilities, and universal recognition. Use QOI when speed matters more than format compatibility — internal asset pipelines, real-time applications, and tooling where you control both the encoder and decoder. For distribution, web delivery, or interchange with other people and systems, PNG remains the correct lossless format choice.

Overview

QOI (Quite OK Image Format) was created by Dominic Szablewski and released in November 2021. It was designed with a radically simple philosophy: achieve compression comparable to PNG but with encoding and decoding speeds orders of magnitude faster. The entire specification fits on a single page, and a complete encoder/decoder can be implemented in approximately 300 lines of C. QOI went viral in the developer community upon release, attracting dozens of implementations across programming languages within weeks. It fills a niche between uncompressed formats (BMP, raw pixel buffers) and computationally expensive lossless formats (PNG), making it ideal for real-time applications, game development, and situations where encode/decode speed matters more than maximum compression.

Technical Specifications

• File extension(s): .qoi
• MIME type: image/qoi (unofficial; not IANA registered)
• Compression type: Lossless. Uses a combination of four simple operations: run-length encoding, index into a 64-entry rolling hash table, small difference encoding (delta from previous pixel), and full RGB/RGBA values. All operations work on individual pixels sequentially.
• Color depth: 24-bit RGB or 32-bit RGBA (8 bits per channel only)
• Max dimensions: 2^32 - 1 pixels in each dimension (limited by 32-bit unsigned header fields). Maximum total pixel count limited by available memory.
• Transparency: Full 8-bit alpha channel (when using RGBA mode)
• Header: 14 bytes total (magic bytes "qoif", width, height, channels, color space)
• Metadata support: None (only color space indicator: sRGB or linear)
• Compression ratio: Typically achieves 70-85% of PNG's compression (files are 15-30% larger than optimized PNG, but far smaller than BMP)
• Speed: Encodes 20-50x faster than libpng, decodes 3-5x faster. Single-pass, no-allocation-needed algorithm.
• Streaming: Can be decoded in a single sequential pass with O(1) memory overhead (just a 64-pixel hash table)

How to Work With It

Opening & Viewing

• Native support: Limited; QOI is not widely supported in mainstream applications yet
• Viewers: XnView MP, ImageGlass (via plugin), qoiview (dedicated viewer)
• Programming: Libraries available for C, C++, Rust, Go, Python, JavaScript, Swift, and 40+ other languages
• Web: JavaScript decoder available for browser-based viewing
• GIMP: Plugin available for import/export

Creating & Editing

• C reference: qoi_write("output.qoi", pixels, &desc) — the entire API is two functions (read/write)
• Python: import qoi; qoi.write("output.qoi", pixel_array) (using qoi PyPI package)
• Rust: qoi::encode_to_vec(&pixels, width, height) (using qoi crate)
• Command line: qoiconv input.png output.qoi (reference implementation converter)
• Game engines: Custom integration is trivial due to format simplicity (300 lines of C)
• Design tip: QOI works best for images with areas of repeated or similar colors. It handles screenshots, UI graphics, and game sprites particularly well.

Converting To/From

• QOI to PNG: qoiconv input.qoi output.png
• PNG to QOI: qoiconv input.png output.qoi
• ImageMagick: Not natively supported; use qoiconv or programmatic conversion
• Python: import qoi; from PIL import Image; pixels = qoi.read("in.qoi"); Image.fromarray(pixels).save("out.png")
• Batch convert: for f in *.png; do qoiconv "$f" "${f%.png}.qoi"; done

Common Use Cases

• Game development (fast texture loading, level streaming, asset caching)
• Real-time applications where encode/decode speed is critical
• Screenshot capture tools (fast lossless encoding without PNG's latency)
• Intermediate format in image processing pipelines
• Embedded systems with limited CPU but sufficient storage
• Replacing raw pixel buffers with modest compression at negligible CPU cost
• Video frame caching (individual frames stored as QOI)
• Educational projects (learning image format implementation)
• Situations where PNG encoding latency is a bottleneck

Pros & Cons

Pros:

• Extremely fast encoding (20-50x faster than PNG)
• Very fast decoding (3-5x faster than PNG)
• Trivially simple to implement (single-page spec, ~300 lines of C)
• Lossless with full alpha support
• No dependencies, no complex configuration
• O(1) memory overhead for decoding
• Open specification, public domain / MIT licensed
• Consistent performance (no pathological cases that explode encoding time)

Cons:

• Files are 15-30% larger than optimized PNG on average
• No metadata support (no EXIF, ICC profiles, or text chunks)
• 8-bit per channel only (no 16-bit, no HDR)
• No interlacing or progressive loading
• Limited mainstream application support
• Not suitable for web delivery (no browser support)
• No standard MIME type registration
• Poor compression for photographic content compared to JPEG/WebP
• No animation support
• Young format with smaller ecosystem

Compatibility

Platform	Support
Web browsers	Not supported
Photoshop	Not supported
GIMP	Via plugin
XnView MP	Supported
Game engines	Custom integration (easy)
ImageMagick	Not supported natively
Programming languages	40+ library implementations
Operating systems	No native preview support

Related Formats

• PNG: The established lossless format QOI positions itself against (better compression, much slower)
• BMP: Uncompressed raster format (QOI provides significant size reduction at minimal CPU cost)
• TGA: Simple format used in game dev (QOI is a modern alternative with better compression)
• WebP (lossless): Better compression than QOI but significantly slower encode/decode
• LZ4-compressed raw pixels: Similar performance niche; QOI achieves better ratios with comparable speed
• FLIF: Free Lossless Image Format (better compression, discontinued in favor of JPEG XL)
• farbfeld: Suckless simple image format (even simpler than QOI but no compression)

Practical Usage

• Use QOI as a fast intermediate format in image processing pipelines where you need lossless round-tripping without PNG's encoding latency.
• Integrate QOI into game engines for texture loading and asset caching -- the trivial decode cost makes it ideal for real-time asset streaming.
• Use qoiconv for batch conversion between QOI and PNG when you need both formats -- it handles the round-trip losslessly.
• Consider QOI for screenshot capture tools where encoding speed directly affects the user experience -- QOI encodes 20-50x faster than PNG.
• Keep a PNG copy for any content that needs web delivery, metadata, or archival -- QOI lacks browser support, EXIF, ICC profiles, and 16-bit depth.
• Implement QOI support in custom tooling by embedding the ~300-line reference C implementation directly rather than adding a library dependency.

Anti-Patterns

• Using QOI for web delivery -- No browser supports QOI natively; use PNG, WebP, or AVIF for web images.
• Choosing QOI over PNG for archival purposes -- QOI lacks metadata support (EXIF, ICC profiles, text annotations) essential for long-term preservation; use PNG for archival.
• Expecting QOI to handle HDR or high bit depth -- QOI supports only 8 bits per channel (24-bit RGB or 32-bit RGBA); use OpenEXR, PNG-16, or AVIF for HDR and high-dynamic-range content.
• Comparing QOI compression to JPEG or WebP lossy -- QOI is lossless and will always produce larger files than lossy formats for photographic content; the comparison should be against PNG and other lossless formats.
• Using QOI for photographic content where file size matters -- QOI's compression is weakest on high-entropy photographic images; PNG and especially WebP lossless achieve better ratios for photos.