Amazing-QR: Artistic and Animated GIF QR Code Generator in Python

Three QR Code Modes and What Each Produces

Amazing-QR produces three distinct output types. A common QR code is a standard black-and-white scannable code, generated by providing a URL or text string and optional size and error correction level flags. An artistic QR code combines the QR pattern with a background image file: the result is a code where the QR modules are laid over the image, producing a black-and-white composite by default, or a colorized version when the `-c` flag is added. An animated GIF QR code applies the same compositing logic to each frame of a GIF file, producing an animated code that remains scannable.

All three modes share the same output format options: `.jpg`, `.png`, `.bmp`, or `.gif`. For animated output, the output filename must end with `.gif`. The README notes that nearly square background images produce better results than rectangular ones, and that large images benefit from a larger `-v` (version) value.

Installing and Using the CLI

Install the package from PyPI:

pip install amzqr

The CLI is `amzqr`. A basic QR code from a URL:

amzqr https://github.com

The output defaults to `qrcode.png` in the current directory. To set a specific version (size) and error correction level:

amzqr https://github.com -v 10 -l Q

The `-v` flag ranges from 1 to 40. The `-l` flag accepts `L`, `M`, `Q`, or `H`, where `H` is the default and highest error correction level. To add a background image and enable colorization:

amzqr https://github.com -p github.jpg -c

To adjust contrast and brightness of the blended image:

amzqr https://github.com -p github.jpg -c -con 1.5 -bri 1.6

Both `-con` and `-bri` default to 1.0. To specify the output filename and directory:

amzqr https://github.com -n github_qr.jpg -d .../paths/

If the output filename matches an existing file, the old file is deleted without warning.

Library API and Agent Integration

The package can be used as a Python library by importing the `amzqr` module:

from amzqr import amzqr

version, level, qr_name = amzqr.run(
    words,
    version=1,
    level="H",
    picture=None,
    colorized=False,
    contrast=1.0,
    brightness=1.0,
    save_name=None,
    save_dir=os.getcwd(),
)

All parameters mirror the CLI flags. The function returns the version, error correction level, and output filename. The `picture` parameter accepts a filename string for the background image.

For AI agent integration, the README describes two options. The first is a skill from the `x-hw/skills` repository, installed with:

npx skills add x-hw/skills --skill generate-amazing-qr-code

The second is an MCP server at `x-hw/amzqr-mcp` for MCP-compatible agents. After installation, the README states that the agent will pick up the skill or MCP server automatically when asked to generate a QR code.

Supported Input Characters and Technical Constraints

The README documents which characters the QR code content can contain. Supported characters are digits 0 through 9, letters a through z and A through Z, and a specific set of punctuation marks: period, comma, colon, semicolon, plus, minus, asterisk, forward slash, backslash, tilde, exclamation mark, at sign, hash, dollar sign, percent, caret, ampersand, backtick, single quote, equals, less than, greater than, square brackets, parentheses, question mark, underscore, curly braces, pipe, and space.

Characters outside this set are not listed as supported. Applications that need to encode Unicode text, CJK characters, or special symbols should verify that the content encodes correctly before using this library.

The only runtime dependency listed in `pyproject.toml` is Pillow (version 8.0.0 to less than 12). Python 3.8 or later is required.

Licence Constraint: GPL-3.0

Amazing-QR is released under GPL-3.0. This licence is copyleft, meaning any software that incorporates the library and is distributed must also be released under GPL-3.0 or a compatible licence. For proprietary applications, this is a hard constraint: distributing closed-source software that links to a GPL-3.0 library is a licence violation.

The pyproject.toml declares `license = { text = "GPLv3" }`. There is no commercial licence option mentioned in the README.

Developers who need to generate QR codes in a proprietary application should evaluate alternatives with permissive licences such as `qrcode` (MIT) or `segno` (BSD). Both libraries support plain QR codes. Neither library supports the animated GIF compositing that distinguishes Amazing-QR. The project has no commercial licence option listed in the README or pyproject.toml.

Alternatives and What Amazing-QR Does Differently

The `qrcode` library is the most commonly used Python QR code generator. It produces standard QR codes and supports basic image styling. It does not support animated GIF codes or the image-blending compositing that Amazing-QR provides. `qrcode` is MIT-licensed.

`segno` is a more feature-complete alternative with support for Micro QR codes and structured append, a richer SVG output, and better compliance with the QR code specification. It does not support GIF animation compositing. `segno` uses BSD licensing.

QR code styling libraries in JavaScript such as `qr-code-styling` provide browser-based artistic QR codes. They run in a different environment and are not relevant for server-side Python pipelines.

Amazing-QR's specific differentiator is the animated GIF output mode combined with the colorized compositing. These are the two capabilities that the alternatives do not cover and that justify the GPL-3.0 constraint for projects where those features are required.

Editorial conclusion

Amazing-QR is a focused tool for developers who need to produce visually distinctive QR codes: a company asset blended into the pattern, an animated GIF branded with a QR code, or a colorized overlay. It is not suited to applications that need only a plain QR code with no visual modification, where lighter libraries with fewer dependencies would suffice. The GPL-3.0 licence is a hard constraint for proprietary applications: any software that incorporates Amazing-QR as a library must comply with GPL-3.0 obligations, which typically means releasing the incorporating software's source under the same or a compatible licence.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. x-hw/amazing-qr on GitHub