qrcode 5.1

QR Code image generator

Pure python QR Code generator

This module uses image libraries, Python Imaging Library (PIL) by default, to generate QR Codes.

It is recommended to use the pillow fork rather than PIL itself.

What is a QR Code?

A Quick Response code is a two-dimensional pictographic code used for its fast readability and comparatively large storage capacity. The code consists of black modules arranged in a square pattern on a white background. The information encoded can be made up of any kind of data (e.g., binary, alphanumeric, or Kanji symbols)

Usage

From the command line, use the installed qr script:

qr "Some text" > test.png

Or in Python, use the make shortcut function:

import qrcode
img = qrcode.make('Some data here')

Advanced Usage

For more control, use the QRCode class. For example:

import qrcode
qr = qrcode.QRCode(
    version=1,
    error_correction=qrcode.constants.ERROR_CORRECT_L,
    box_size=10,
    border=4,
)
qr.add_data('Some data')
qr.make(fit=True)

img = qr.make_image()

The version parameter is an integer from 1 to 40 that controls the size of the QR Code (the smallest, version 1, is a 21x21 matrix). Set to None and use the fit parameter when making the code to determine this automatically.

The error_correction parameter controls the error correction used for the QR Code. The following four constants are made available on the qrcode package:

ERROR_CORRECT_L

About 7% or less errors can be corrected.

ERROR_CORRECT_M (default)

About 15% or less errors can be corrected.

ERROR_CORRECT_Q

About 25% or less errors can be corrected.

ERROR_CORRECT_H.

About 30% or less errors can be corrected.

The box_size parameter controls how many pixels each “box” of the QR code is.

The border parameter controls how many boxes thick the border should be (the default is 4, which is the minimum according to the specs).

Other image factories

You can encode as SVG, or use a new pure Python image processor to encode to PNG images.

The Python examples below use the make shortcut. The same image_factory keyword argument is a valid option for the QRCode class for more advanced usage.

SVG

On Python 2.6 must install lxml since the older xml.etree.ElementTree version can not be used to create SVG images.

You can create the entire SVG or an SVG fragment. When building an entire SVG image, you can use the factory that combines as a path (recommended, and default for the script) or a factory that creates a simple set of rectangles.

From your command line:

qr --factory=svg-path "Some text" > test.svg
qr --factory=svg "Some text" > test.svg
qr --factory=svg-fragment "Some text" > test.svg

Or in Python:

import qrcode
import qrcode.image.svg

if method == 'basic':
    # Simple factory, just a set of rects.
    factory = qrcode.image.svg.SvgImage
elif method == 'fragment':
    # Fragment factory (also just a set of rects)
    factory = qrcode.image.svg.SvgFragmentImage
else:
    # Combined path factory, fixes white space that may occur when zooming
    factory = qrcode.image.svg.SvgPathImage

img = qrcode.make('Some data here', image_factory=factory)

Two other related factories are available that work the same, but also fill the background of the SVG with white:

qrcode.image.svg.SvgFillImage
qrcode.image.svg.SvgPathFillImage

Pure Python PNG

Install the following two packages:

pip install git+git://github.com/ojii/pymaging.git#egg=pymaging
pip install git+git://github.com/ojii/pymaging-png.git#egg=pymaging-png

From your command line:

qr --factory=pymaging "Some text" > test.png

Or in Python:

import qrcode
from qrcode.image.pure import PymagingImage
img = qrcode.make('Some data here', image_factory=PymagingImage)

Change log

Version 5.1

• Make qr script work in Windows. Thanks Ionel Cristian Mărieș

• Fixed print_ascii function in Python 3.

• Out-of-bounds code version numbers are handled more consistently with a ValueError.

• Much better test coverage (now only officially supporting Python 2.6+)

Version 5.0

• Speed optimizations.

• Change the output when using the qr script to use ASCII rather than just colors, better using the terminal real estate.

• Fix a bug in passing bytecode data directly when in Python 3.

• Substation speed optimizations to best-fit algorithm (thanks Jacob Welsh!).

• Introduce a print_ascii method and use it as the default for the qr script rather than print_tty.

Version 5.0.1

• Update version numbers correctly.

Version 4.0

• Made qrcode work on Python 2.4 - Thanks tcely. Note: officially, qrcode only supports 2.5+.

• Support pure-python PNG generation (via pymaging) for Python 2.6+ – thanks Adam Wisniewski!

• SVG image generation now supports alternate sizing (the default box size of 10 == 1mm per rectangle).

• SVG path image generation allows cleaner SVG output by combining all QR rects into a single path. Thank you, Viktor Stískala.

• Added some extra simple SVG factories that fill the background white.

Version 4.0.1

• Fix the pymaging backend not able to save the image to a buffer. Thanks ilj!

Version 4.0.2

• Fix incorrect regex causing a comma to be considered part of the alphanumeric set.

• Switch to using setuptools for setup.py.

Version 4.0.3

• Fix bad QR code generation due to the regex comma fix in version 4.0.2.

Version 4.0.4

• Bad version number for previous hotfix release.

Version 3.1

• Important fixes for incorrect matches of the alpha-numeric encoding mode. Previously, the pattern would match if a single line was alpha-numeric only (even if others wern’t). Also, the two characters { and } had snuck in as valid characters. Thanks to Eran Tromer for the report and fix.

• Optimized chunking – if the parts of the data stream can be encoded more efficiently, the data will be split into chunks of the most efficient modes.

Version 3.1.1

• Update change log to contain version 3.1 changes. :P

• Give the qr script an --optimize argument to control the chunk optimization setting.

Version 3.0

• Python 3 support.

• Add QRCode.get_matrix, an easy way to get the matrix array of a QR code including the border. Thanks Hugh Rawlinson.

• Add in a workaround so that Python 2.6 users can use SVG generation (they must install lxml).

• Some initial tests! And tox support (pip install tox) for testing across Python platforms.

Version 2.7

• Fix incorrect termination padding.

Version 2.6

• Fix the first four columns incorrectly shifted by one. Thanks to Josep Gómez-Suay for the report and fix.

• Fix strings within 4 bits of the QR version limit being incorrectly terminated. Thanks to zhjie231 for the report.

Version 2.5

• The PilImage wrapper is more transparent - you can use any methods or attributes available to the underlying PIL Image instance.

• Fixed the first column of the QR Code coming up empty! Thanks to BecoKo.

Version 2.5.1

• Fix installation error on Windows.

Version 2.4

• Use a pluggable backend system for generating images, thanks to Branko Čibej! Comes with PIL and SVG backends built in.

Version 2.4.1

• Fix a packaging issue

Version 2.4.2

• Added a show method to the PIL image wrapper so the run_example function actually works.

Version 2.3

• When adding data, auto-select the more efficient encoding methods for numbers and alphanumeric data (KANJI still not supported).

Version 2.3.1

• Encode unicode to utf-8 bytestrings when adding data to a QRCode.

Version 2.2

• Fixed tty output to work on both white and black backgrounds.

• Added border parameter to allow customizing of the number of boxes used to create the border of the QR code

Version 2.1

• Added a qr script which can be used to output a qr code to the tty using background colors, or to a file via a pipe.