Create Scannable QR Images with qrencode

You will turn text, a URL or a file into a QR Code image that can be saved as PNG or SVG. This guide uses qrencode 4.1.1, the version installed with the Debian package checked for this article. Allow about 10 minutes for a first useful image. No elevated privileges are needed: write to a directory where your account can create files.

Check the installed tool

1. Confirm the version before relying on examples.

qrencode --version

Expected output starts like this:

qrencode version 4.1.1

The command writes an image to standard output only when you explicitly use -o -. Otherwise, use -o with a filename. The default image type is PNG, the default pixel size is 3, the default margin is 4, and error correction defaults to level L.

Make a PNG from a string

1. Encode a small, safe test value into a new file.

qrencode -o qrencode-test.png 'https://example.com/'

There is normally no success message. Verify the file rather than waiting for terminal output:

file qrencode-test.png

Expected output identifies a PNG image, with dimensions depending on the encoded data and the selected options. Open the file with an image viewer or scan it with a phone. The shell quotes around the input are useful even for a URL: they prevent spaces or shell metacharacters in later values from being interpreted by the shell.

Use standard input for longer or generated data

1. Pipe text to qrencode without placing it in the command's argument list.

printf '%s\n' 'https://example.com/account?id=12345' | qrencode -o account-qr.png

With no positional string, qrencode reads standard input. The newline printed by printf becomes part of the input, so use printf '%s' when the exact bytes matter:

printf '%s' 'device-123|temporary-enrolment-code' | qrencode -o device-qr.png

For an existing file, use -r:

qrencode -r message.txt -o message-qr.png

Check that the source exists and contains what you intend before encoding it. QR Codes can carry private data, and anyone who can scan the image can read it. Do not put passwords, recovery codes or long-lived access tokens in an image you will share.

Choose SVG when the image must scale

1. Select SVG explicitly when the QR Code will be placed in a document or web page and needs to scale cleanly.

qrencode --type=SVG --output=event-qr.svg 'https://example.com/events/demo'

Verify that the output is recognised as SVG:

file event-qr.svg

Use PNG for the simplest exchange with image viewers and printers. Use SVG for layout systems that preserve vector graphics. The --inline option is only useful with SVG and removes the XML declaration; it does not convert a PNG or make the QR data safer.

Balance size and error correction

1. Set a larger module size and a stronger correction level when the printed or displayed image may be damaged.

qrencode --size=6 --margin=4 --level=H --output=label-qr.png 'https://example.com/asset/ABC123'

The correction levels run from L, the lowest, through M and Q to H, the highest. Stronger correction makes the symbol less tolerant of lost modules, but it also needs more room for the same data. The margin is the quiet border around the symbol, measured in modules. Keep it present unless you have tested the final scanner and layout.

The size option changes the number of pixels used for each module. It does not reduce the data or force a smaller QR version. Leave the symbol version automatic for normal data. A QR Code has versions 1 to 40, with larger versions carrying more data. You can request a minimum version with --symversion, but a value that is too small will fail if the data does not fit.

Know when to use strict or structured mode

Automatic version selection is usually the least distracting choice. If a receiving system requires a particular minimum version, test it explicitly:

qrencode --symversion=5 --strict-version --output=version-5.png 'https://example.com/short-code'

With --strict-version, qrencode stops instead of adjusting the version when the input is too large. A failure exits with status 1. Check that status in a script:

if qrencode --symversion=1 --strict-version --output=small.png 'REPLACE_WITH_INPUT'; then
    echo 'QR image created'
else
    echo 'Input does not fit the requested version' >&2
fi

Structured symbols split data across several QR images, but the manpage requires a version with -v. Use this only when the scanner and workflow support structured append:

qrencode --structured --symversion=40 --level=L --read-from=bigfile.txt --output=bigfile.png

The output is written as numbered files such as bigfile-01.png and bigfile-02.png. Treat the whole numbered set as one output. Do not upload only the first part.

Handle input and output failures

1. Read the error, then check paths and permissions before changing options.

A missing input file, an unwritable destination, or data that cannot fit the requested version is a command failure. Run a harmless diagnostic with a destination in the current directory:

test -r message.txt && test -w . && qrencode --read-from=message.txt --output=message-checked.png

This command does not need sudo. Adding elevated privileges can create files owned by root and does not fix a bad input path. If you made a test image that is no longer wanted, remove that specific generated file only:

rm -- qrencode-test.png

That removal cannot be undone from qrencode, so inspect the filename first. Keep source text and any shared QR image separate from temporary test output. If you need to replace an image used by a service or document, make a new filename, verify it, then update the consumer deliberately rather than overwriting a live asset during experimentation.

Done means

• The installed qrencode version is known.
• The input bytes are understood, including whether a newline is included.
• The output type, correction level and margin suit the scanner and destination.
• file recognises the generated image, and a real scan returns the expected data.
• No secret or temporary test data is being shared accidentally.