go-qr

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

Playground · Getting started · Documentation · API reference

• 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 8 to 21× faster than skip2/go-qrcode and decoding about 7× faster than gozxing, with orders of magnitude fewer allocations (benchmarks).

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

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

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.

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.

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.

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.

MIT