phoboslab/qoi

★ 7,480CAudience · developerComplexity · 2/5LicenseSetup · easy

Mindmap

mindmap
  root((QOI format))
    What it does
      Lossless compression
      Encode images
      Decode images
    Compared to PNG
      Similar file size
      Much faster encode
      Much faster decode
    Implementation
      Single header file
      C and C++ only
      No build steps
    Ecosystem
      GIMP plugin
      Godot plugin
      Unity and Unreal
      macOS and Windows
    Limits
      400M pixel max
      No streaming decode
      No format extensions

mindmap root((QOI format)) What it does Lossless compression Encode images Decode images Compared to PNG Similar file size Much faster encode Much faster decode Implementation Single header file C and C++ only No build steps Ecosystem GIMP plugin Godot plugin Unity and Unreal macOS and Windows Limits 400M pixel max No streaming decode No format extensions

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Replace PNG for image saving and loading in a game engine where read/write speed matters more than absolute file size.

USE CASE 2

Drop the single .h file into any C or C++ project to add fast lossless image export without extra dependencies or build steps.

USE CASE 3

Use a QOI plugin for GIMP, Paint.NET, or Godot to edit and save .qoi images directly in your existing creative or game workflow.

USE CASE 4

Benchmark your image pipeline by swapping PNG for QOI to see how much throughput you gain when processing large numbers of images.

Tech stack

CC++

Getting it running

Difficulty · easy Time to first run · 5min

MIT license, use freely for any purpose including commercial projects, just keep the copyright notice.

In plain English

QOI, short for "Quite OK Image Format," is a lossless image format designed to be fast at both encoding and decoding. The entire implementation is a single C/C++ header file under the MIT license, so adding it to a project means dropping in one file with no extra build steps. The format sits in a practical middle ground between raw speed and compression size. Its compression output is roughly comparable to PNG, though typically not as tight as the most optimized PNG libraries. Where QOI stands out is throughput: encoding and decoding are substantially faster than PNG, which matters when reading or writing many images quickly. Because the format specification itself is extremely simple, it has been ported to dozens of programming languages, including Python, Rust, Go, Java, Zig, Swift, Elixir, OCaml, and many others. The format is finalized and intentionally has no version number in file headers. A working QOI implementation today will be compatible with all QOI files in the future. The project does not plan to extend the format or accept pull requests that change it. This reference implementation loads an entire image into memory before processing, and is capped at 400 million pixels. It is not a streaming decoder. For images beyond that size, the README points to third-party implementations. The recommended file extension is .qoi and the recommended MIME type is image/qoi. The ecosystem around QOI has grown considerably. There are plugins for Windows Explorer, macOS Finder, GNOME, GIMP, Paint.NET, Godot, Unity, and Unreal Engine 5. Tools exist for viewing QOI images in terminals, desktop applications, and web browsers, and Microsoft PowerToys added QOI preview and thumbnail support for Windows Explorer. Format-level benchmarks comparing QOI, PNG, and other options are published at qoiformat.org.

Copy-paste prompts

Prompt 1

I want to use the QOI format in my C game engine to save screenshots faster than PNG. Show me the minimal C code to encode a raw RGBA pixel buffer into a .qoi file using the single-header library.

Prompt 2

Using the QOI reference implementation in C, write code that loads a .qoi image file into memory and returns its width, height, and a pointer to the raw pixel data.

Prompt 3

Explain the QOI file format encoding scheme from the spec, what are the different run-length and pixel-difference opcodes it uses to compress image data?

Prompt 4

I need to load QOI images in Python. Show me how to install and use a Python QOI library to open a .qoi file and convert it to a Pillow Image object.

Prompt 5

Compare QOI and PNG for my use case: I need to save thousands of lossless screenshots per hour in a C++ application. What are the tradeoffs in file size, encode speed, and decode speed?

Open on GitHub → Explain another repo

← phoboslab on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.