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, and Grade grades a rendering or a photo of a print by the quality parameters of ISO/IEC 15415.
• A decoder that reads photos. Perspective, lens distortion, glare, blur, photos of screens and codes with a damaged finder pattern, and with DecodeAll every code in a photo. 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 8 to 21× faster than skip2/go-qrcode and decoding 3 to 6× 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

Tutorial	Getting started
Guides	Encoding · Rendering · Styling · Decoding · Payloads · Batch processing · Troubleshooting · Command-line tool · AI assistants (MCP)
Reference	API on pkg.go.dev · Errors · Standards support · Changelog
Background	How it works · Performance

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