go-qr

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

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