Project Nayuki

QR Code generator library


This project aims to be the best, clearest library for generating QR Codes. My primary goals are flexible options and absolute correctness. Secondary goals are compact implementation size and good documentation comments.

This work is an independent implementation based on reading the official ISO specification documents. I believe that my library has a more intuitive API and shorter code length than competing libraries out there. The library is designed first in Java and then ported to TypeScript, Python, Rust, C++, and C. It is open source under the MIT License. For each language, the codebase is roughly 1000 lines of code and has no dependencies other than the respective language’s standard library.

Live demo (JavaScript)

You can generate QR Code symbols conveniently on this web page, powered by the TypeScript version of this library.

QR Code:
Error correction:
Output format:
pixels per module
Colors: Light = , dark =
Version range: Minimum = , maximum =
(−1 for automatic, 0 to 7 for manual)
Boost ECC:


Core features:

  • Available in 6 programming languages, all with nearly equal functionality: Java, TypeScript/JavaScript, Python, C++, C, Rust

  • Significantly shorter code but more documentation comments compared to competing libraries (a competitive analysis is provided near the bottom of this page)

  • Supports encoding all 40 versions (sizes) and all 4 error correction levels, as per the QR Code Model 2 standard

  • Output format: Raw modules/pixels of the QR symbol

  • Detects finder-like penalty patterns more accurately than other implementations

  • Encodes numeric and special-alphanumeric text in less space than general text

  • Open-source code under the permissive MIT License

Manual parameters:

  • User can specify minimum and maximum version numbers allowed, then library will automatically choose smallest version in the range that fits the data

  • User can specify mask pattern manually, otherwise library will automatically evaluate all 8 masks and select the optimal one

  • User can specify absolute error correction level, or allow the library to boost it if it doesn’t increase the version number

  • User can create a list of data segments manually and add ECI segments (all languages except C)

Optional advanced features (Java only):

  • Encodes Japanese Unicode text in kanji mode to save a lot of space compared to UTF-8 bytes

  • Computes optimal segment mode switching for text with mixed numeric/alphanumeric/general/kanji parts

Source code

This library is designed with essentially the same API structure and naming in multiple languages for your convenience: Java, TypeScript, Python, Rust, C++ – but a different API in C to avoid dynamic allocation. Regardless of the language used, the generated results are guaranteed to be identical because the algorithms are translated faithfully.

For my own convenience when designing and testing the code, the Java language version of the QR Code generator library is considered to be the master reference version. The TypeScript, Python, Rust, and C++ versions are ported from the Java version, with a balance between writing idiomatic code in the target language but also not deviating too much from the Java version’s design. When in doubt, please consult the Java version to read the more extensive documentation comments and to check what types and values are considered legal.

The full project repository is available at GitHub:

Java language (SE 7 and above)

The library:,,
Optional advanced logic (SE 8+):
Runnable demo program:

Available as a package on The Central Repository: io.nayuki qrcodegen
Online Javadoc documentation: io.nayuki.qrcodegen

Usage examples:

import java.awt.image.BufferedImage;
import java.util.List;
import javax.imageio.ImageIO;
import io.nayuki.qrcodegen.*;

// Simple operation
QrCode qr0 = QrCode.encodeText("Hello, world!", QrCode.Ecc.MEDIUM);
BufferedImage img = toImage(qr0, 4, 10);  // See QrCodeGeneratorDemo
ImageIO.write(img, "png", new File("qr-code.png"));

// Manual operation
List<QrSegment> segs = QrSegment.makeSegments("3141592653589793238462643383");
QrCode qr1 = QrCode.encodeSegments(segs, QrCode.Ecc.HIGH, 5, 5, 2, false);
for (int y = 0; y < qr1.size; y++) {
	for (int x = 0; x < qr1.size; x++) {
		(... paint qr1.getModule(x, y) ...)

This compact, no-dependency library is your one-stop shop for all your QR Code generation needs. To learn how to use the API, please read the demo program’s source code, and maybe skim the library code’s inline Javadoc comments.

For the following practical reasons, Java is my best choice for the reference version because it ensures a high degree of correctness and allows writing detailed documentation comments:

  • Static type checking prevents dumb typos in names and subtly incorrect arguments being passed (such as byte[] vs. BitBuffer). (Whereas Python and JavaScript don’t have static type checking.)

  • There is a strong and clear separation between public interfaces and private implementation details. (Whereas privacy is only a naming convention in Python, and feasible but hacky/ugly in JavaScript.)

  • Javadoc is expressive and has a consistent syntax. (Whereas Python, JavaScript, and C++ do not have single dominant syntax for documentation comments.)

  • Java has good standard libraries for file, image, and network handling, and the language is memory-safe. This makes it easier to build a correct application quickly. (Whereas C++ programming easily gets into third-party library frenzy and undefined behavior hell – even though it does have static typing and proper public/private just like Java.)

  • Only the Java version of my library contains the advanced segment encoder logic for kanji mode and optimal segment mode switching.

For heavy-duty use, there is a fast version of this Java library. Its speed-up is about 2 to 5 times (see the benchmark timings for both libraries).

TypeScript language

The library: qrcodegen.ts
Demo matching all other languages: qrcodegen-output-demo.ts
The demo on this page: qrcodegen-input-demo.ts

Usage examples:

// Name abbreviated for the sake of these examples here
const QRC = qrcodegen.QrCode;

// Simple operation
const qr0 = QRC.encodeText("Hello, world!", QRC.Ecc.MEDIUM);
const svg = toSvgString(qr0, 4);  // See qrcodegen-input-demo

// Manual operation
const segs = qrcodegen.QrSegment.makeSegments("3141592653589793238462643383");
const qr1 = QRC.encodeSegments(segs, QRC.Ecc.HIGH, 5, 5, 2, false);
for (let y = 0; y < qr1.size; y++) {
	for (let x = 0; x < qr1.size; x++) {
		(... paint qr1.getModule(x, y) ...)

The TypeScript code must be compiled into JavaScript in order to be executed in a web browser, Node.js server, etc. Outputting to ECMAScript 5 is supported, though higher versions are more readable.

This TypeScript library’s high-level organization of classes, public/private members, and types on variables all resemble Java. The code uses ECMAScript 2015 (ES6) features like classes, let/const, arrow functions, and for-of loops; additionally it uses TypeScript namespaces.

This codebase benefits TypeScript developers because it is fully in TypeScript instead of annotating JavaScript code with declaration files (.d.ts), and it compiles with no errors/warnings under the --strict flag. The codebase benefits JavaScript developers because the type annotations provide documentation about what value types are expected as inputs and outputs, and TypeScript is a gentle extension of the JavaScript language instead of being radically different (such as CoffeeScript, Dart, etc.).

JavaScript language (5 and above)

The JavaScript version of this library can be found in the releases section on GitHub. The code is machine-generated, compiled from TypeScript but with a bit of hand-tweaking of the header. The code is not in the project’s version control tree. These precompiled pieces of JavaScript code are offered in two flavors: ECMAScript 5 compatibility (for Microsoft Internet Explorer 11) or ES6/2015 compatibility (for all modern web browsers).

Historically, I had a hand-written version of this library for ES5. Due to ES5’s lack of classes, the code structure had to be significantly rearranged from the Java version. Then I learned TypeScript, ported the code, and maintained both language versions simultaneously. Later on, I decided to remove the hand-written JavaScript version in favor of compilation from TypeScript – because TS syntax is an easy-to-understand extension of JS, and the TS compiler allows me to use new language features (like ES6) while still being able to compile down to an older version (like ES5).

Python language (3 and above)

The library:
Runnable demo program:

Available as a package on PyPI: pip install qrcodegen

Usage examples:

from qrcodegen import *

# Simple operation
qr0 = QrCode.encode_text("Hello, world!", QrCode.Ecc.MEDIUM)
svg = to_svg_str(qr0, 4)  # See qrcodegen-demo

# Manual operation
segs = QrSegment.make_segments("3141592653589793238462643383")
qr1 = QrCode.encode_segments(segs, QrCode.Ecc.HIGH, 5, 5, 2, False)
for y in range(qr1.get_size()):
	for x in range(qr1.get_size()):
		(... paint qr1.get_module(x, y) ...)

Only Python 3 is supported. Please read the demo program’s source code to get a good idea of how to use this library. For further information, consult the big comment at the top of the library source file that summarizes all the public classes, functions, and methods available in the module.

Historically, this library was born as Python 2-and-3 polyglot code. This compatibility was maintained throughout development up to and including version 1.6.0 at commit 71c75cfeb0f0 (2020-03-05). Thereafter, the library removed Python 2 support and now only works on Python 3.

C++ language (11 and above)

The library: qrcodegen.hpp, qrcodegen.cpp Runnable demo program: QrCodeGeneratorDemo.cpp

Usage examples:

#include <string>
#include <vector>
#include "QrCode.hpp"
using namespace qrcodegen;

// Simple operation
QrCode qr0 = QrCode::encodeText("Hello, world!", QrCode::Ecc::MEDIUM);
std::string svg = toSvgString(qr0, 4);  // See QrCodeGeneratorDemo

// Manual operation
std::vector<QrSegment> segs =
QrCode qr1 = QrCode::encodeSegments(
segs, QrCode::Ecc::HIGH, 5, 5, 2, false);
for (int y = 0; y < qr1.getSize(); y++) {
	for (int x = 0; x < qr1.getSize(); x++) {
		(... paint qr1.getModule(x, y) ...)

The code requires C++11 to compile due to numerous convenient features unavailable in C++03, such as better handling of temporary values and const instance fields. The code is fully portable because it only depends on the C++ standard library but not any OS APIs (e.g. POSIX), and it avoids implementation-dependent assumptions on integer widths. The code completely avoids all undefined behavior (e.g. integer overflow, type punning, etc.).

Unfortunately, the library is unsuitable for embedded microcontroller environments (e.g. Arduino) due to the use of the heavyweight STL std::vector class and dynamic memory allocation. The C version is the one specifically designed to supported embedded environments.

C language (99 and above)

The library: qrcodegen.h, qrcodegen.c
Runnable demo program: qrcodegen-demo.c

Usage examples:

#include <stdbool.h>
#include <stdint.h>
#include "qrcodegen.h"

// Text data
uint8_t qr0[qrcodegen_BUFFER_LEN_MAX];
uint8_t tempBuffer[qrcodegen_BUFFER_LEN_MAX];
bool ok = qrcodegen_encodeText("Hello, world!",
tempBuffer, qr0, qrcodegen_Ecc_MEDIUM,
qrcodegen_VERSION_MIN, qrcodegen_VERSION_MAX,
qrcodegen_Mask_AUTO, true);
if (!ok)

int size = qrcodegen_getSize(qr0);
for (int y = 0; y < size; y++) {
	for (int x = 0; x < size; x++) {
		(... paint qrcodegen_getModule(qr0, x, y) ...)

// Binary data
uint8_t dataAndTemp[qrcodegen_BUFFER_LEN_FOR_VERSION(7)]
= {0xE3, 0x81, 0x82};
uint8_t qr1[qrcodegen_BUFFER_LEN_FOR_VERSION(7)];
ok = qrcodegen_encodeBinary(dataAndTemp, 3, qr1,
qrcodegen_Ecc_HIGH, 2, 7, qrcodegen_Mask_4, false);

Notes about this C version of the library:

  • Many projects choose the C programming language instead of C++, due to simpler semantics, faster compilation, and more robust development tools (debuggers, etc.). This version of the library serves this market.

  • The other 6 language versions are facsimiles of each other in terms of code architecture, but this C library had to be written from scratch to avoid dynamic memory allocation and to fit C’s object-less programming paradigm.

  • The complete lack of heap allocation makes this code suitable for constrained environments such as operating system kernels and small microcontrollers (e.g. having 16 KiB of RAM). The C++ code, with its use of the heavyweight Standard Template Library (STL) and dynamic memory allocation in std::vector, is probably unsuitable for such environments.

  • The code requires a C99-compliant compiler and standard library to compile. Note that older versions of Microsoft Visual C++ (before the 2013 release) only supported C89, which make it more difficult to use my library.

  • This code is portable and platform-independent by design. It makes no assumptions on endianness, integer type widths, two’s complement, etc. It only relies on behavior mandated by the C standard, for example the fact that int must be at least 16 bits wide.

  • This C code uses much more low-level indexing and raw buffer passing than the other 6 language versions, so the correctness of the logic is much less obvious at a glance. The safety of this C library was assured in multiple ways: Being mindful of value ranges and choosing suitably sized integer types, designing arithmetic calculations to carefully avoid overflow, running the code under Clang’s UndefinedBehaviorSanitizer and AddressSanitizer and MemorySanitizer, and feeding millions of random inputs then testing for identical output against other language versions.

  • The code only uses integer arithmetic, no floating-point arithmetic. This is good for small microcontroller CPUs without an FPU.

  • Here are a photo and video showing the C version of the QR Code generator library running on a PJRC Teensy 3.1 microcontroller. Remember that in the worst case, rendering a version 40 QR Code requires 8 KB of RAM (including temporary scratch space).

Rust language

The library:
Runnable demo program:

Available as a package on qrcodegen
Online documentation at qrcodegen

Usage examples:

extern crate qrcodegen;
use qrcodegen::QrCode;
use qrcodegen::QrCodeEcc;
use qrcodegen::QrSegment;

// Simple operation
let qr = QrCode::encode_text("Hello, world!",
let svg = to_svg_string(&qr, 4);  // See qrcodegen-demo

// Manual operation
let text: &str = "3141592653589793238462643383";
let segs = QrSegment::make_segments(text);
let qr = QrCode::encode_segments_advanced(&segs, QrCodeEcc::High,
    Version::new(5), Version::new(5), Some(Mask::new(2)), false).unwrap();
for y in 0 .. qr.size() {
	for x in 0 .. qr.size() {
		(... paint qr.get_module(x, y) ...)

Notes about this Rust version of the library:

  • Has no crate dependencies, only relying on the standard library.

  • The source code files are laid out in directories according to the Cargo project format.

  • The higher level text APIs take &str (UTF-8 byte sequence), whereas the lower APIs take &[char] (Unicode code point sequence).

  • Unlike the {Java, JavaScript, TypeScript, Python, C++} language versions which throw exceptions for various conditions, the Rust version panics if an input violates a precondition (e.g. number out of range, character value outside of designated set). However, the encoder functions return Err if the data is too long to fit in a QR Code, because this precondition is quite difficult for a library user to check ahead of time.

Third-party ports

A number of people have translated this library to other programming languages. These third-party libraries vary in their quality and faithfulness to my original work, and are not backed by my personal guarantee.

QR Code technology overview

The QR Code standard defines a method to encode a string of characters or bytes into a grid of dark and light pixels. The text could be numbers, names, URLs, et cetera. Because the standard uses a 2D barcode, it can store much more information than a traditional 1D barcode. To illustrate for comparison, a 1D barcode usually stores 10 to 20 digits, while a QR code often stores 50 textual characters. Note that a QR Code barcode simply represents static data – the barcode does not inherently cause an action to be executed.


Some of the frequently used official terminology have non-intuitive meanings, as summarized below:

QR Code

A popular international standard (symbology), created by Denso Wave, that specifies how messages are converted to barcodes. “QR Code” is a registered trademark and wordmark of Denso Wave Incorporated.

QR Code symbol

A single 2D graphical barcode, which results from the QR Code generation process. Informally this is called a “QR code” (without using the word symbol) or a barcode.


A dark or light pixel in a QR Code symbol. Note that a module can be scaled to occupy multiple pixels on a screen or in an image file.


A way of measuring the size of a symbol, from 1 to 40. Version 1 has 21×21 modules, version 2 has 25×25, ..., and version 40 has 177×177. Note that all 40 versions are defined in a single standard, and this term differs from the conventional meaning of the word version.


Indicates the revision of the QR Code standard. (The word model here corresponds with the conventional meaning of the word version.) Model 1 QR codes are outdated and essentially never seen. Model 2 QR codes are widespread and dominant. Model 2 also has an extension called Micro QR codes (not implemented in my library). Note that model 1 defines versions 1 through 14, whereas model 2 QR defines versions 1 through 40, allowing much more data capacity.

Generation procedure

The process (and high-level algorithm) for generating a QR Code symbol is as follows:

  1. Choose the text (Unicode string) or binary data (byte string) to encode.

  2. Choose one of the 4 error correction levels (ECL). A higher ECC level will yield a barcode that tolerates more damaged parts while preserving the payload data, but will tend to increase the version number (i.e. more modules in width and height).

  3. Encode the text into a sequence of zero or more segments. A segment in byte mode can encode any data, but using alphanumeric or numeric mode is more compact if the text falls into these subsets.

  4. Based on the segments to be encoded and the ECL, choose a suitable QR Code version to contain the data, preferably the smallest one.

  5. Concatenate the segments (which have headers and payload) and add a terminator. The result is a sequence of bits.

  6. Add padding bits and bytes to fill the remaining data space (based on the version and ECL).

  7. Reinterpret the bitstream as a sequence of bytes, then divide it into blocks. Compute and append error correction bytes to each block. Interleave bytes from each block to form the final sequence of 8-bit codewords to be drawn.

  8. Initialize a blank square grid based on the version number.

  9. Draw the function patterns (finders, alignment, timing, version info, etc.) onto the appropriate modules. This is formatting overhead to support the QR Code standard, and does not encode any user data.

  10. Draw the sequence of (data + error correction) codewords onto the QR Code symbol, starting from the bottom right. Two columns at a time are used, and the scanning process zigzags going upward and downward. Any module that was drawn for a function pattern is skipped over in this step.

  11. Either manually or automatically choose a mask pattern to apply to the data modules. If masking automatically, then all 8 possibilities are tested and the one with the lowest penalty score is accepted. Note that the format information is redrawn to reflect the mask chosen.

  12. We are now finished the algorithmic parts of QR Code generation. The remaining work is to render the newly generated barcode symbol as a picture on screen, or save it as an image file on disk.

In the context of the steps above, my QR Code generator library provides the logic to perform steps 3 through 11. The other steps must be performed by the user of the library.

Compared to competitors

qrcodegen by Project Nayuki (Java, JavaScript, Python, C++, C, Rust)
  • Relatively compact implementation – 1260 lines of code for the Java version (without QrSegmentAdvanced), 970 lines for TypeScript, 890 lines for Python, 1340 lines for C++, 1280 lines for C, 1270 lines for Rust. (Each version is independent, so it’s meaningless to add up all the line counts.)

  • The extra advanced features (kanji mode, optimal segment mode switching) in the Java version cost another 290 lines of code and 110 lines of constants

  • Line counts include the generous amount of comments for functions, comments for blocks of statements, and blank lines – but exclude header comments of author and license info

  • Contains as few tables of numerical constants as needed – unlike competitors, this implementation does not have tables of: data capacities per version, alignment pattern positions, error correction block sizes, expanded format and version bits, Reed-Solomon divisor polynomials, or finite field exp/log tables

  • The QR Code and helper objects are all immutable, thus simplifying user operation and reducing errors from accidental misuse of the API

  • Creates a single segment in numeric, alphanumeric, or byte mode; encodes custom list of segments

  • The version reviewed was 8f9c1be97466, dated 2021-07-28

qr.js by Kang Seonghoon (JavaScript)
  • About 800 lines of core code in the library

  • Code is quite concise, minimizing the size of constant tables and avoiding verbose logic

  • Includes generous comments explaining the overview of behavior

  • The organization and behavior of subfunctions (such as computing the number of bits and characters, and painting different sets of QR Code modules) are surprisingly similar to my design, despite the fact that he published one year earlier than me and I had never seen his code until months after I published my library

  • The code is more compact than mine in areas such as the bit buffer and segment encoding, because they are inlined into the QR Code generation workflow instead of being exported as freestanding modules

  • Creates a single segment in numeric, alphanumeric, or byte mode; cannot encode custom list of segments

  • The version reviewed was 52f0409a22c5, dated 2015-04-11

qr.js by Alasdair Mercer (JavaScript)
  • About 1200 lines of core code in the library

  • qr.js: 800 lines for main QR encoding logic, 110 lines for numerical tables, 300 lines for image export; note that generateFrame() is a 400-line monolithic function

  • Code includes a good number of comments inside and outside functions

  • Only supports ASCII text and silently corrupts non-ASCII Unicode characters; creates a single segment always in byte mode; cannot encode custom list of segments

  • The version reviewed was 18decea6ba9a, dated 2015-11-11. The library has since been renamed to QRious

QR Code Generator by Kazuhiko Arase (JavaScript, others)
  • About 1840 lines of core code in the JavaScript library

  • qrcode.js: 860 lines of code for main QR encoding logic, 340 lines for numerical tables, 360 lines for HTML and GIF output, 280 lines for binary encoding utilities

  • Contains no comments at all to describe functions; sparsely contains low-level comments to describe chunks of logic statements

  • The author has ported the library to multiple languages, but with different levels of features. The JavaScript version appears to be the most feature-complete, the Java version has fewer features but more documentation comments, and others have fewer features and comments.

  • The version reviewed was 94f0023b802a, dated 2016-01-23

QR-Logo by Henrik Kaare Poulsen (JavaScript)
  • About 2900 lines of core code in the library

  • Supports encoding and decoding QR Code symbols

  • qrcodedecode.js: 970 lines of code for an encoder with the typical features, 1100 lines for a decoder that can operate on imperfect images (i.e. not axis-aligned with whole-pixel module size), 410 lines for tables of numbers

  • reedsolomon.js: 420 lines of code for Reed-Solomon encoding, decoding syndrome calculation, error correction, polynomial arithmetic

  • The version reviewed was b3a77e8f0145, dated 2011-10-15

qrcode by Lincoln Loop (Python)
  • About 1300 lines of core code in the library

  • 420 lines for text accumulation, module drawing, terminal printing

  • 550 lines for tables of various constants, QR symbol penalty calculation, segment encoding logic, bit buffer class, block error correction and interleaving, bitstream formatting

  • 360 lines for finite field tables, error correction block sizes, polynomial class

  • Code documentation/comments are neglectfully sparse in most places, but has some good comments for the public methods of the QRCode class

  • Creates a single segment in numeric, alphanumeric, or byte mode; creates imperfectly optimized list of segments; encodes custom list of segments

  • The version reviewed was b79ab5b3e598, dated 2016-03-15

PyQRCode by Michael Nooner (Python)
  • About 2800 lines of core code in the library

  • 900 lines of code for segment encoding, bitstream formatting, ECC generation, module drawing, symbol penalty calculation; 500 lines for export logic to various image formats

  • 620 lines for mostly character encoding logic, some one-liner wrapper methods for exporting images, and long documentation comments

  • 750 lines of almost entirely numeric constants

  • Generally speaking the function-level documentation comments are long (and longer than my typical writing), there are comments every 5 or so lines within functions to describe the algorithmic processes (just like I do), but the implementation seems to use a lot of code just to implement basic behaviors

  • The version reviewed was 467f9a2a3c04, dated 2016-02-26

qrcode by kennytm (Rust)
  • About 2800 of core code in the library, when the embedded pieces of test and benchmark code are removed

  • Includes plenty of documentation comments throughout, and at least 200 lines of tables of numbers in

  • Apparently supports encoding Micro QR Codes and kanji mode

  • The version reviewed was ba77f8bc2d9b, dated 2017-07-18

qr by Russ Cox (Go)
  • About 1850 lines of core code in the library, excluding tests

  • Spends hundreds of lines of code on tables of constants

  • Code contains few comments, not easy to understand the public API that a developer should use

  • No penalty calculation or automatic masking

  • Implements a simple PNG encoder from scratch

  • The version reviewed was ca9a01fc2f95, dated 2018-06-05

Zint by Ismael Luceno and Robin Stuart (C)
  • About 2400 lines of code among qr.c/h and reedsol.c/h

  • Can encode many types of 1D and 2D barcodes, and includes GUI application

  • Uses heap memory allocation; mutable global variables to store current Reed-Solomon tables (not thread-safe)

  • Low-density logic in code, not much API documentation comments, 100 lines of QR constants

  • The version reviewed was 3432bc9aff31, dated 2013-07-09

libqrencode by Kentaro Fukuchi (C)
  • About 6800 lines of core code in the library

  • The most popular C library for QR Code encoding by far

  • Has third-party wrappers for various high-level languages, and numerous patches over the years

  • Uses dynamic memory allocation, unlike my zero-allocation C library

  • Supports even more advanced features absent from my library, such as Micro QR codes and structured append mode

  • Code seems confusing with over 50 public API functions

  • The version reviewed was 1ef82bd29994, dated 2017-03-15

More info