go-qr

Zero-dependency QR Code encoding, styling and decoding for Go.

Playground · Getting started · Documentation · API reference

Why go-qr

• Complete. QR Code Model 2 as specified by ISO/IEC 18004: all 40
  versions, all four error correction levels, numeric, alphanumeric, byte
  and Kanji modes, ECI, structured append and GS1.
• Compact codes by default. Encode switches modes within the text, picks
  the smallest version and raises error correction into spare capacity.
• Styled, and still readable. Dot and rounded modules, round finders,
  colors, gradients and logos. Verify renders the result, decodes it and
  checks the contrast, so you know a design scans before you publish it.
• A decoder that reads photos. Perspective, lens distortion, glare,
  photos of screens and codes with a damaged finder pattern. It reads about
  as many real photos as zxing-cpp and more than WeChat, ZBar and gozxing
  (comparison).
• Fast and dependency-free. Only the standard library. Encoding is about
  3× faster than skip2/go-qrcode and decoding about 7× faster than
  gozxing, with orders of magnitude fewer allocations
  (benchmarks).

Install

go get github.com/piglig/go-qr/v2

Requires Go 1.23 or later. Upgrading from v1? See Upgrading to v2.

Quick start

package main

import (
	"log"
	"os"

	"github.com/piglig/go-qr/v2"
)

func main() {
	code, err := qr.Encode("https://github.com/piglig/go-qr")
	if err != nil {
		log.Fatal(err)
	}
	png, err := code.PNG(qr.WithModuleShape(qr.ModuleRounded))
	if err != nil {
		log.Fatal(err)
	}
	if err := os.WriteFile("qr.png", png, 0o644); err != nil {
		log.Fatal(err)
	}
}

Decode an image:

res, err := qr.Decode(img) // any image.Image
fmt.Println(res.Text)

The getting started tutorial goes from here to a
styled, verified code in a few minutes.

Documentation

Command-line tool

go install github.com/piglig/go-qr/tools/generator@latest
generator encode -png hello.png "Hello, world!"
generator decode hello.png

See the CLI guide for every flag.

AI assistants

go-qr-mcp is an MCP server that lets
Claude, Cursor and other assistants decode, generate and inspect QR Codes
exactly, instead of guessing from pixels, and flags risky content such as
lookalike URLs or embedded 2FA secrets:

go install github.com/piglig/go-qr/mcp/cmd/go-qr-mcp@latest
claude mcp add go-qr -- go-qr-mcp

See the MCP guide for other clients and the tools.

Contributing

Bug reports, ideas and pull requests are welcome. Read
CONTRIBUTING.md for how to set up the repository, run the
tests and fuzzers, and send a change. Report security issues privately as
described in SECURITY.md.

License

MIT