Amazing-QR: the amzqr CLI for artistic and animated GIF QR codes

What amzqr does that a plain QR library does not

A standard QR library turns a string into a grid of black and white modules. Amazing-QR does that too, but its selling point is the second half: it takes a picture file and merges the code into that picture, in black and white or in colour, and it accepts a .gif as the source image so the output code can animate. The README lists three output classes: common qr-code, artistic qr-code (black & white or colorized), and animated qr-code (black & white or colorized). The audience is developers who want a code that looks like a piece of artwork for a poster, a profile page, a payment card or a chat sticker, rather than a scanner-friendly label on a shipping box. The CLI is the main entry point; a Python API exposes the same parameters for scripted use. The project also ships integration paths for AI agents: an agent skill named generate-amazing-qr-code in the x-hw/skills repository, and a separate MCP server at x-hw/amzqr-mcp.

How the blending works, and where the parameters bite

The mechanism is layered. amzqr.run() first encodes the words string into a QR matrix at a chosen version (1 to 40) and error correction level (L, M, Q or H). When no picture is supplied, that matrix is written straight to an image file. When a picture is supplied through -p, the code is composited onto the image, and the -c flag switches the result from black and white to colour. Two numeric knobs, -con for contrast and -bri for brightness, both defaulting to 1.0, adjust the picture before or during that composite. The default error correction level is H, the highest, which is what makes the overlay survivable: the encoder spends more of the symbol on redundancy, so the drawn picture can cover part of the pattern without destroying readability. That is a real design decision, not a detail. A higher level means more modules for the same payload, so the code gets denser, and on a photograph the density is exactly what makes scanning harder. The version parameter is the other half of that trade: -v 1 to -v 40 sets the symbol size, and the README notes the default size depends on both the number of words and the level. Nothing in the README documents how the picture is mapped onto modules, so the visual result is something you judge by generating and scanning, not by reading.

Install amzqr and generate a first artistic QR code

The package is on PyPI as amzqr (the project was formerly named MyQR). The README gives one install line; Python 3.8 or newer is required according to pyproject.toml, and Pillow between 8.0.0 and 12 is the only runtime dependency.

pip install amzqr

After installation the amzqr command is on your PATH, because pyproject.toml maps the amzqr console script to amzqr.terminal:main. The simplest use takes a URL and writes qrcode.png into the current directory.

amzqr https://github.com

To make an artistic code, point -p at an image file. The README states the picture is taken from the same directory as the program, and the result is black and white unless you add -c.

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

For an animated result, pass a .gif as the picture. The README notes that if you also set -n, the output filename must end in .gif. The same call is available from Python, which returns the version, level and output name.

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(),
)

What you should see is an image file in the directory you chose with -d, named with -n or defaulting to qrcode.png. Open it and scan it with a phone before you ship it anywhere.

The output file gets overwritten, and other edges of the CLI

The README is explicit that if the output name matches an existing file, the old one is deleted. There is no backup and no prompt. In a script that regenerates codes on a schedule, that means the previous artifact disappears the moment the new run starts, so any pipeline that reads the file afterwards needs to account for the window. Two more constraints sit in the argument list. First, -n accepts only .jpg, .png, .bmp and .gif extensions; anything else is outside what the README documents. Second, the animated path is gated on the input being a GIF, so a static picture can never produce a moving code, and the README does not describe how frame count or frame timing in the source GIF maps to the output. The supported character set is a separate section in the README, which is where you should look before encoding anything beyond a URL. Contrast and brightness take floats, and the README gives no bounds, so extreme values are untested ground. Finally, the project is licensed GPL-3.0, which matters if you plan to distribute the generated tooling rather than the images.

Amazing-QR versus a plain encoder such as qrcode

The Python qrcode package, which this project depends on indirectly through its own stack, takes the opposite approach: it produces a clean matrix and stops there. If you want a logo in the middle, you composite it yourself, and you decide how much of the symbol to cover. Amazing-QR packages that compositing step, adds the colour and brightness controls, and handles GIF input, which a bare encoder does not. The difference shows up in what you give up. A plain encoder lets you reason about module size, quiet zone and error correction directly, and its output is predictable. Amazing-QR hides the mapping behind -p, -c, -con and -bri, so the only way to know whether a given photograph yields a scannable code is to generate it and try. If your requirement is a code that must scan from a printed poster at two metres, the plain encoder plus a manual overlay gives you more control. If your requirement is a code that looks like the poster, Amazing-QR is the shorter path. The related searches people type, such as "QR code styling" and "Python generate QR code for URL", map onto exactly this split.

Maintenance, packaging and the GPL-3.0 licence

The last push to the default branch was on 2026-09-16, so the repository is current as of this writing, and it is not archived. There are no releases retrieved for the repository, but the package is published to PyPI, and pyproject.toml keeps the version dynamic from amzqr.__version__.__version__, so the PyPI listing is the place to check what you are installing. The dependency range Pillow>=8.0.0,<12 means an upgrade of Pillow past 12 will require a corresponding change here; that is the main upgrade cost you can see from the packaging metadata. The dev group lists pytest, pytest-benchmark and ruff, and the top-level tree includes tests/ and benchmarks/, so the project has its own test and benchmark setup, though the README does not describe how to run them. On licensing: the package is GPL-3.0, declared as text in pyproject.toml with license-files disabled so the metadata stays at version 2.1. GPL-3.0 is a copyleft licence, which is a consideration if you link the library into software you distribute; this is not legal advice, and if that scenario applies to you, read the LICENSE.md file in the repository and get your own counsel.

Editorial conclusion

Amazing-QR fits people who need a decorative or animated QR code produced from the command line or from Python in one call, and who are comfortable with the GPL-3.0 licence. It is the wrong tool if you need a maintained web service, a JavaScript-only build, or a scannability guarantee on a busy background image. Before adopting it, install amzqr on your target Python version, generate one code from a real photograph with -c, and scan the result with the phones your audience actually uses.

Frequently asked questions

Official sources

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