go-qrcode turns QR generation into a set of option functions

Styling is the reason to pick this library over a bare encoder

The stated purpose of the project is to help Go developers generate QR codes with customized styles, such as colour, block size, block shape and icon. That is the whole pitch, and it is worth being clear about what it means. A QR code is a machine-readable matrix barcode, first designed in 1994 for the automotive industry in Japan, using four standardized encoding modes, numeric, alphanumeric, byte or binary, and kanji, with extensions also used. The default look of a generated code is a black-and-white grid of squares, and most libraries give you that plus a file. This one treats the appearance as a set of options: custom and circle cell shapes, background and foreground colour, border width, a logo image in the centre, gradient foreground, and halftone rendering. The audience is developers building something user facing, where a code with a logo and rounded modules reads as part of the product.

Installation and the smallest useful program

The package is fetched with the go tool.

go get -u github.com/yeqown/go-qrcode/v2

The quick start in the README shows the whole flow: create a QR code from a string, open a writer, and save through it.

qrc, err := qrcode.New("https://github.com/yeqown/go-qrcode")
if err != nil {
	fmt.Printf("could not generate QRCode: %v", err)
	return
}

w, err := standard.New("../assets/repo-qrcode.jpeg")
if err != nil {
	fmt.Printf("standard.New failed: %v", err)
	return
}

The example file at example/main.go is the reference version, and the example directory has a go.mod of its own, so the examples build separately from the library module. The last step is qrc.Save(w), which hands the generated code to the writer.

Encoding mode and error correction are separate decisions

Styling is the visible half of the API, but the options that determine whether a code can be scanned are set independently. Encoding mode is a constant block with five values, starting from EncModeNone and continuing through numeric, alphanumeric, byte and kanji.

const (
	// EncModeNone mode ...
	EncModeNone encMode = 1 << iota
	// EncModeNumeric mode ...
	EncModeNumeric
	// EncModeAlphanumeric mode ...
	EncModeAlphanumeric
	// EncModeByte mode ...
	EncModeByte
	// EncModeKanji mode ...
	EncModeKanji
)

Error correction is a second constant block with four levels, each carrying its recovery percentage in the comment: low at 7 percent, medium at 15 percent, quart at 25 percent and highest at 30 percent, with the medium level described as a good default choice. These two blocks are what let you trade density for resilience, and they are the setting a reader should think about first, because a code that looks good and scans badly is the common failure of a styled QR generator. The README also lists automatic analysis of the QR version by source text, and generation across version 1 to version 40.

Writers decide where the code ends up, not what it looks like

The writer abstraction is the structural decision in this library, and it separates output from appearance. The standard writer prints the QR code into a file and a stream, the terminal writer prints it into a terminal, the file writer prints it into files, and the compressed writer generates it on a very small scale. The README states that you can also write your own writer by implementing the Writer interface, and the repository has a writer/ directory at the root with a README for it. The reason this matters is that the same styled code, with a logo and a gradient, can then be rendered as a PNG, printed to a terminal, or pushed through a compressor, without regenerating the matrix. The standard writer in the quick start is opened with a file path ending in .jpeg, which tells you the encoder format is chosen by the writer's output target rather than by an option on the code itself.

The v2 rewrite broke the v1 API on purpose

The migration note is blunt: go-qrcode.v2 is a major upgrade from v1, it is not backward compatible, and v2 redesigned the API to be more flexible and powerful by splitting features into different modules according to functionality. The three modules named are the v2 core, the writer/imageFile module for the standard writer, and the writer/terminal module. A migration example lives at example/migrating-from-v1/main.go, which is where anyone with v1 code should start. This is a real cost for an existing user: the import paths change and the option functions are new, so an upgrade is a code change, not a version bump. For a new project it costs nothing, and the module path carries the major version, github.com/yeqown/go-qrcode/v2, so the go tool can resolve v1 and v2 side by side if you need to hold the old one during the transition.

The repository shows a real encoder, not a wrapper

The file layout is a useful signal about how much of the specification is implemented here. At the root sit encoder.go, encoder_option.go, matrix.go, matrix_type.go, mask.go and mask_evaluation.go, alongside chardet.go for character detection and utilities.go, plus version.go and version_cfg.go. Tests exist for most of them, and the go.mod requires github.com/yeqown/reedsolomon for error correction coding and golang.org/x/text, with testify for the tests. The go directive is 1.19, and there is a go.work file in the root along with a go.work.sum, so the repository is set up as a Go workspace covering the library and the separate example module. This is a from-scratch implementation of the QR specification, which is why the halftone and gradient rendering options exist here at all rather than being bolted on to someone else's encoder.

Where a styled QR code stops being a good idea

Every visual option reduces the contrast and regularity that a scanner relies on, and the library gives you no way to measure that cost. A logo covering the centre of a code eats modules that carry data, a gradient shifts the foreground colour across the symbol, circle cells and halftone dots reduce the solid area a scanner has to sample, and a low error correction level removes the redundancy that would have absorbed the damage. The result is that a decorative code is a code you should scan yourself, on the actual screen or print, before you ship it to users, and the repository offers no test pattern or validation helper to make that check. There is a second limitation in the shape of the API: the visual and the functional settings are separate option functions with no combined profile, so a service that generates many codes has to construct the same option set every time and has no easy way to assert that a given style still scans.

Editorial conclusion

go-qrcode suits a Go service that needs a QR code to look like it belongs to a product rather than a default generator, and it suits anyone who wants the QR encoded in the browser through the WebAssembly build. It is the wrong choice when you want a minimal dependency, because the encoder pulls in a Reed-Solomon implementation and golang.org/x/text for character detection, and the wrong choice when you need the strict standard output of a barcode scanner in a controlled environment, because every styling option trades scan reliability for appearance and the library does not document a way to measure that trade-off. Before adopting it, check the encoding mode and error correction level you need, since WithEncodingMode and WithErrorCorrectionLevel are separate from the visual options, and pick a writer that matches your output target. The last push was on 2026-08-06 and the current release is v2.2.5 from 2025-02-14.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. yeqown/go-qrcode on GitHub