---
id: qreader
version: "3.16"
license: MIT
license_treatment: permissive
maintenance: aging
---

# qreader — Robust and Straight-Forward solution for reading difficult and tricky QR codes within images in Python. Supported by a YOLOv8 QR Segmentation model.

License: permissive · Maintenance: aging · Downloads: 79.8K/mo

## What it is and what it does

QReader is a Python library for detecting and decoding QR codes from images, combining a YOLOv8-based detector with Pyzbar decoding. It specializes in handling difficult QR codes—those that are damaged, poorly lit, rotated, or otherwise challenging—by applying adaptive image preprocessing after detection. The library exposes a simple API: instantiate a QReader object once, then call detect_and_decode() on images to retrieve decoded strings, or call detect() to get bounding boxes and confidence scores for each QR found.

The package depends on numpy for array operations, opencv-python for image manipulation, pyzbar for the actual QR decoding step, and qrdet (the standalone YOLOv8 detector model). It ships as a pure Python wheel with low install friction. Configuration options include model size (nano to large), detection confidence threshold, character re-encoding for non-ASCII charsets, and custom model weight storage paths—useful for constrained environments.

Use it for:

- Batch scanning of QR codes from document images or photographs in data entry workflows.
- Automated inventory or asset tracking systems that need to read QR codes from imperfect camera feeds.
- Mobile app backends that process user-uploaded images containing QR codes.
- Quality control in manufacturing: detecting and decoding QR labels on products or packaging.
- Archival digitization projects where QR codes may be faded, creased, or partially obscured.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

QReader detects and decodes QR codes from images using a YOLOv8 model combined with Pyzbar, handling difficult and damaged QR codes through image preprocessing.

Yes, if you need robust QR detection and decoding from real-world images. The library is production-stable (Development Status 5), has low install friction, carries no security vulnerabilities, and uses a permissive license. Maintenance is aging but not abandoned. Install only if you can satisfy the system-level pyzbar dependencies and accept that the last release was in February 2025.

## Install

pip install qreader
uv add qreader
poetry add qreader

## Installing qreader

Before you install: Low friction: pure Python wheel with four runtime dependencies (numpy, opencv-python, pyzbar, qrdet). Maintenance is aging—last commit 2025-02-22, no recent releases—but the repo remains active and unarchived with 418 stars.

License in practice: MIT license (permissive) places no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart:

pip install qreader

from qreader import QReader
import numpy

qreader = QReader()
decoded_text = qreader.detect_and_decode(image=image)

On Linux, install libzbar0; on macOS, install zbar; on Windows, may require Visual C++ Redistributable. System-level pyzbar dependencies required before package installation.

Verify before relying:

- Accuracy and speed trade-offs between model sizes ('n', 's', 'm', 'l') in production scenarios.
- Performance on QR codes with severe damage, rotation, or perspective distortion.
- Memory footprint and inference latency for batch processing or real-time applications.
- Compatibility with modern Python versions (requires_python is unspecified).

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: aging
- Downloads: 79.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

qr code detection and decoding, read qr codes from images, difficult qr code recognition, yolov8 qr detection, batch qr code scanning, qr code segmentation, damaged qr code recovery, qr-code-detection, computer-vision, yolov8

[View on SkillFed](https://skillfed.io/packages/qreader) · [View on PyPI](https://pypi.org/project/qreader/)