QOI (.qoi)

---
name: qoi
description: "QOI is a simple, fast lossless image format designed for ultra-fast encoding/decoding; ideal for real-time apps and game development when speed matters more than maximum compression."
metadata:
  tags: "file-formats, image-formats, lossless-compression, run-length-encoding, delta-encoding, real-time, game-development"
  source: "https://skilldb.dev/skills/file-formats-skills/qoi"
  pack: "file-formats-skills"
  category: "Technology & Engineering"
---

# QOI (.qoi)

## When to use this skill
Use when the user says things like:
- "Explain what QOI (.qoi) is and where it’s best used."
- "When should I use the QOI image format?"
- "Provide use cases for QOI in game development."
- "Compare QOI to PNG in terms of speed and size."
- "Describe QOI encoding/decoding approach."


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

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