# QR scanning on Linux

> The reliable path on Linux is the command line, install zbar and run zbarimg file.png to decode an image, or zbarcam for a webcam. zxing-cpp offers a more capable modern decoder. For a no-install option, a browser-based scanner decodes screenshots client-side in Firefox or Chromium.

Source: https://useqr.app/docs/scanning/qr-scanning-on-linux · Last reviewed 2026-08-21 · UseQR is free forever, MIT licensed, no signup.

---

## The CLI is the dependable path

No Linux desktop environment ships QR decoding in its shell, and GUI apps for it —
GNOME's Decoder, various applets — exist but come and go with distributions. The tool
that is always one package away is **zbar**:

```bash
sudo apt install zbar-tools    # Debian/Ubuntu (Fedora, Arch: package "zbar")
zbarimg screenshot.png
# QR-Code:https://example.com
# scanned 1 barcode symbols from 1 images
```

`zbarimg` reads any common image format, prints the payload prefixed with the symbology,
and exits non-zero when nothing decodes — which makes it script-friendly. Useful flags:
`--raw` to drop the `QR-Code:` prefix, `-q` to silence the summary line.

For live scanning with a webcam:

```bash
zbarcam            # opens the default camera, prints payloads to stdout
zbarcam --raw /dev/video2   # a specific camera, clean output
```

Each decoded code prints as a line to stdout the moment it is recognised, so you can
pipe an all-day scanning station into a file or a script — the poor man's version of
[batch scanning](/docs/scanning/batch-scanning-many-qr-codes).

## zxing-cpp for the codes zbar misses

zbar is venerable and fast, but its decoder predates a lot of modern robustness work.
**zxing-cpp** — the actively maintained C++ descendant of the
[ZXing](/glossary/zxing) project — copes better with damaged, dense or oddly lit codes.
The quickest way to use it is the Python binding:

```bash
pip install zxing-cpp pillow
python3 -c "import zxingcpp, PIL.Image as I; print(zxingcpp.read_barcode(I.open('code.png')).text)"
```

A sensible division of labour: `zbarimg` first because it is instant, zxing-cpp when
zbar returns nothing. If you are wiring decoding into software rather than a shell, the
library landscape is mapped on
[decoding QR codes programmatically](/docs/developers/decode-a-qr-code-programmatically).

## The screenshot pipeline

The common desktop case — a code in an email or web page — is a two-step: screenshot
with whatever your environment provides (`gnome-screenshot`, `spectacle`, `grim`,
`scrot`), then `zbarimg` the file. On Wayland compositors where screenshot tooling is in
flux, remember the decoder only needs an image file; any capture route works.

## The no-install option

A [browser-based scanner](/scan) decodes uploaded images and webcam frames client-side
in Firefox or Chromium — nothing sent to a server, no packages touched. It is the right
answer on a locked-down machine, and the decoded-text-first behaviour is what you want
for [codes you do not trust](/docs/security/how-to-check-a-qr-code-before-opening). How
in-browser decoding actually works is covered in
[browser scanning](/docs/scanning/qr-scanning-in-a-browser).

## Generating, while you are here

The reverse direction is a one-liner too — `curl` against a keyless API:

```bash
curl -o qr.png "https://useqr.app/api/v1/qr?data=https://example.com&size=512"
```

The full API surface, including SVG output and decode endpoints, is on the
[curl guide](/docs/developers/generate-a-qr-code-with-curl).

## FAQ

### How do I scan a QR code on Linux?
Install zbar (zbar-tools on Debian/Ubuntu) and run zbarimg on a screenshot or image of
the code, or zbarcam for live webcam scanning. Alternatively use a browser-based
scanner, which needs no installation.

### What is the zbarimg command for QR codes?
zbarimg file.png decodes any QR code in the image and prints its contents. Add --raw for
just the payload and -q to suppress the summary, which makes it convenient in scripts
and pipelines.

### Why does zbar fail on some QR codes that phones read?
zbar's decoder is older and less tolerant of damage, dense modules and uneven lighting.
zxing-cpp, via its Python binding or CLI, decodes many of the codes zbar misses and is
the standard second attempt.

### Can I scan QR codes on a Linux server without a GUI?
Yes — that is zbarimg's natural habitat. It reads image files headlessly and exits
non-zero when nothing decodes, so it slots into shell scripts, cron jobs and CI
pipelines directly.

## Try it

- https://useqr.app/scan
- https://useqr.app/validate