django-qr-code

4.2.0 · active · verified Fri Apr 17

An application that provides tools for displaying QR codes on your Django site. It supports generation of QR codes as SVG, PNG, or Base64 embedded images, via both Django template tags and a Python API. The current version, 4.2.0, released in May 2025, actively tracks Django and Python releases, ensuring compatibility with the latest versions.

Common errors

```
ModuleNotFoundError: No module named 'Pillow'
```
cause Attempting to generate PNG QR codes without the Pillow library installed, which is required for image processing.

fix Install Pillow: `pip install Pillow` or install `django-qr-code` with the `pil` extra: `pip install "django-qr-code[pil]"`.
```
django.urls.exceptions.NoReverseMatch: Reverse for 'qr_code_from_text' not found. 'qr_code' is not a registered namespace.
```
cause The `qr_code.urls` module is not correctly included in the project's `urls.py` or the specified namespace is incorrect.

fix Add `path('qr_code/', include('qr_code.urls', namespace='qr_code'))` to your project's `urlpatterns`.
```
PydanticUserError: Pydantic 2.x requires a Pydantic 2.x compatible Pydantic-settings.
```
cause Your Pydantic version is incompatible with `django-qr-code` 4.1.0+. It requires Pydantic >= 2.7 for API view validation.

fix Upgrade Pydantic to a compatible version: `pip install "pydantic>=2.7,<3.0"`.

Warnings

breaking `django-qr-code` versions 4.1.0 and later dropped support for Python versions older than 3.10.
Fix: Upgrade your Python environment to 3.10 or newer, or pin `django-qr-code` to `<4.1.0` if using an older Python version.
breaking Versions 4.1.0 and later require Pydantic >= 2.7. Older Pydantic versions are no longer supported.
Fix: Upgrade Pydantic: `pip install "pydantic>=2.7,<3.0"`.
gotcha Generating QR codes as PNG images (e.g., `image_format="png"`) requires the `Pillow` library to be installed.
Fix: Install `Pillow` explicitly: `pip install Pillow` or install `django-qr-code` with the `pil` extra: `pip install "django-qr-code[pil]"`.
gotcha The `qr_code.urls` must be included in your project's `urls.py` with the correct namespace (`namespace='qr_code'`) for template tags and API views to function correctly.
Fix: Add `path('qr_code/', include('qr_code.urls', namespace='qr_code'))` to your project's `urlpatterns`.
gotcha The `get_or_make_cached_embedded_qr_code` utility (new in 4.2.0) requires a Django caching backend to be configured and active in your `settings.py` to cache QR codes effectively.
Fix: Configure a caching backend in your `settings.py`, e.g., `CACHES = {'default': {'BACKEND': 'django.core.cache.backends.locmem.LocMemCache'}}`.

Install

pip install django-qr-code Base installation
pip install "django-qr-code[pil]" With Pillow for PNG image support

Imports

load qr_code (template tag)
```
{% load qr_code %}
```
Used in Django templates to enable QR code generation tags.
QRCodeOptions
```
from qr_code.qrcode.utils import QRCodeOptions
```
For configuring QR code generation parameters programmatically.
make_qr_code_with_options
```
from qr_code.qrcode.utils import make_qr_code_with_options
```
Function to generate QR codes programmatically without caching.
get_or_make_cached_embedded_qr_code
```
from qr_code.qrcode.cache import get_or_make_cached_embedded_qr_code
```
New in 4.2.0 for caching generated embedded QR code HTML, requires Django caching backend.
include qr_code.urls
```
path('qr_code/', include('qr_code.urls', namespace='qr_code'))
```
Adds QR code generation URLs to your project's routing for template tags and API.

Quickstart

To quickly integrate `django-qr-code`, first add it to your `INSTALLED_APPS` and include its URL patterns in your project's `urls.py`. Then, use the `{% qr_from_text %}` template tag in any Django template to generate and display QR codes. Ensure `Pillow` is installed if generating PNG images.

# myproject/settings.py
INSTALLED_APPS = [
    # ... other apps
    'qr_code',
]

# myproject/urls.py
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('qr_code/', include('qr_code.urls', namespace='qr_code')), # Add this line
    # ... other paths
]

# myapp/templates/myapp/my_template.html
{% load qr_code %}

<h1>My QR Code</h1>
<p>This is a QR code for example.com:</p>
{% qr_from_text "https://example.com" size="t" image_format="svg" %}

<p>Or a bigger PNG with custom alt text:</p>
{% qr_from_text "https://my-app.com/secret" size="m" image_format="png" alt="Secret link" %}

view raw JSON →