A Small Python Library for Quiet QR Codes: Meet terminalqr

Sometimes the useful part of a workflow is the small bridge between two devices. A laptop can be running a local tool, while the person who needs it is holding a phone; copying a long address across that gap is a needless interruption. terminalqr is a compact Python library for turning short text and links into QR codes right in the terminal, without adding a runtime dependency.

The engine: deliberately small

The library grew out of a practical LAN file-sharing server. At startup, the server chooses an available port and prints a QR code containing the local address and an access token. A phone can scan it and connect without someone having to type a long URL by hand.

That job does not need a large rendering stack. terminalqr uses Python’s standard library to create a QR Model 2 symbol and return its modules as a Boolean matrix: True is dark, False is light. It can render that matrix for a terminal or print a payload directly.

The boundaries are intentional. The encoder produces version 5, error-correction level L, byte-mode symbols with a fixed mask. It accepts up to 106 UTF-8 bytes. That is enough for short links and small labels, not long documents or arbitrary binary files. It does not create PNG or SVG files as a library feature.

The experience: scan instead of retyping

The smallest use is a single Python call:

from terminalqr import print_qr

print_qr("hello world")

For a short URL, the same function can print a scannable terminal symbol. The command-line interface works too:

terminalqr "hello world"

The output is built for the place it appears: ANSI background colors in an interactive terminal, and Unicode blocks when output is redirected. The result is a quiet hand-off from a developer’s screen to a nearby phone.

A small public repository, with clear edges

The source and installation instructions live at github.com/ljlabs/terminal-qr. After installation, QR generation is local; the library does not send its payload to a QR service. Installing from GitHub does, of course, fetch the package source from GitHub.

The repository is publicly visible, but it currently has no license file. Public visibility makes the source inspectable; it does not by itself grant reuse rights. That is a boundary to settle before incorporating the code into other projects.

For developers thinking about how a small tool can connect otherwise separate parts of a workflow, Vynder’s guide to lightweight protocol bridges offers a useful adjacent perspective. Here, the bridge is simpler: a short string leaves a terminal and arrives on a phone.

Where it helps

• Local dashboards and file sharing: show a nearby phone the address of a temporary service without reading out an IP address and port.
• Workshops and support desks: turn a short setup link or device hand-off into something people can scan.
• Small command-line tools: add a QR output path without carrying a runtime dependency for a narrowly defined task.

For South African teams working across mixed devices or busy shared spaces, this can remove one small point of friction. It works best when the destination is short, the devices can reach one another, and the user already trusts the laptop running the service. A QR code is not encryption: anyone who can scan it can read its contents, so treat access tokens and private links accordingly.

The hand-off ends on a mobile screen, which is why scanability is only part of the experience. Vynder’s mobile-first UX guide for South African websites covers the next step: making the page that opens feel clear and responsive on a phone.

A focused encoder beside broader alternatives

• Compared with a full QR package: terminalqr has no runtime dependencies and keeps its API small. A general QR library is the better fit when you need configurable error correction, multiple symbol sizes, images, logos, or export formats.
• Compared with an online QR generator: generation happens locally after installation, so a short payload does not need to be sent to a separate QR website. The library still does not protect a payload that someone else can scan.
• Compared with typing a link: a QR scan reduces transcription mistakes, but the fixed 106-byte ceiling means it is best for compact destinations.

A modest tool, used on purpose

terminalqr is not trying to replace the whole QR ecosystem. It makes one repetitive step—showing short text or a nearby link—simple to inspect and easy to add to a Python workflow. When the job grows beyond that narrow shape, a broader encoder is the right tool. Until then, one small square can be enough to connect the screen in front of you with the device in your hand.