Skip to main content

anpr2mqtt{ align=left }

anpr2mqtt

Rhizomatics Open Source

PyPI - Version Ruff Coverage Tests pre-commit.ci status Github Deploy CodeQL Dependabot Updates

ANPR MQTT Bridge

A simple way to integrate CCTV cameras with built-in ANPR (Automatic Number Plate Recognition, aka ALPR or Automatic License Plate Recognition) to MQTT for Home Assistant integration, or any other MQTT consumer. Running under Docker is preferred but not necessary.

All that is needed is for the camera to be configured to upload images on plate recognition, by ftp, NAS or whatever else. ANPR2MQTT monitors the directory where the images lands and publishes plate information to MQTT. Its simple, requires no proprietary vendor APIs ( or differing ONVIF implementations ), and Home Assistant gets a copy of the actual annotated detection image to use on dashboards or to attach to notifications.

While intended for vehicle plate detection, it can be used to watch for and analyze any file, so for example uploaded face detection, missing object, unattended baggage or line crossing images. A single anpr2mqtt instance can watch multiple paths and patterns for different cameras and events.

The enrichment, including DVLA lookup, can also be extended to licence plates recognized by Frigate ( see Frigate License Plate Recognition), assuming that frigate/events and frigate/tracked_object_update topics are on the same MQTT broker.

Features

  • Minimal configuration
  • File System Integration
    • Watches directory for ANPR camera images using Watchdog
      • Uses inotify on Linux, or equiv on other operating systems for efficient listening to file system events without continual polling
    • Extracts target ( for example licence plate ), timestamp and event type information from filenames
  • Home Assistant Integration.
  • Plate Enrichment
    • OCR-based extraction of fields using tesseract-ocr
      • By default direction detection (Forward/Reverse)
      • Corrections by regular expression to fix OCR mis-readings
    • Tracks and counts previous sightings
    • Configurable to classify plates as known, to be ignored or as a potential threat
    • Regular expression based corrections, for known plates that the ANPR sometimes mis-reads
    • Fuzzy match corrections for known plates, based on Levenshtein algorithm
    • UK Only
      • DVLA Lookup if API_KEY provided, for detailed MOT and tax information
      • Lookups cached for configurable time
  • Auto clear vehicle state optionally, after configurable time
  • Debug Tools built-in

Docker Deployment

Build and run with Docker, example docker-compose.yaml provided.

Configuration

ANPR2MQTT uses pydantic-settings, which means configuration can happen in a variety of ways, and these can be combined - yaml configuration file, environment variables, Docker Secrets, built-in defaults, and .env file or command line arguments.

CLI Arguments

Every configuration setting can be passed as a command line argument, using dot notation for nested settings. This is the highest-priority source and overrides all other configuration.

uvx anpr2mqtt --mqtt.host 192.168.1.10 --mqtt.port 1884 --log_level DEBUG

Run uvx anpr2mqtt --help to see all available flags, and find more information at Debug Tools

When running outside Docker, OCR also needs the tesseract binary installed, e.g. brew install tesseract on macOS.

Home Assistant Integration

See Home Assistant Integration for configuration and example notification automation.

Environment Variables

pydantic-settings needs double underscores for environment variables in config sections. For example, MQTT__HOST means set the value host in the mqtt config section.

Env Variable Description Default
MQTT__HOST MQTT broker hostname localhost
MQTT__PORT MQTT broker port 1883
MQTT__TOPIC_ROOT MQTT topic for events anpr2mqtt
MQTT__USER MQTT username -
MQTT__PASS MQTT password -
LOG_LEVEL Python logging level INFO
DVLA__API_KEY API Key for Gov API Lookup -

Image Filename Format

Expected format: YYYYMMDDHHMMSSmmm_PLATE_VEHICLE_DETECTION.jpg

Example: 20180502174029596_A2GEO_VEHICLE_DETECTION.jpg

A regular expression can be defined to match different file name formats.

Image Box Coordinates

Where cameras provide an estimated direction for the vehicle, this can be captured via OCR and included in the response. See OCR for an explanation and examples.

Auto Clear

By default, the state will be reset back to unavailable 5 minutes after a detection, while the image will be left present as record of last known vehicle. This behavior can be changed ( to switch off auto clear, or change the time lag, or also clear image ) using the autoclear configuration for each event.

- camera: shed
  watch_path: /ftp/shedcam
  autoclear:
    post_event: 360
    state: True
    image: False

Corrections

The licence plate detection may mis-read or miss some of the characters of the plate. When the result is published to MQTT, both the raw original and corrected versions are provided.

Two mechanisms help with this:

Fuzzy Matching

The Levenshtein method is used to compare the plate against a list of known plates in the configuration, subject to a maximum distance tolerance ( number of mismatched characters ) defined by auto_match_tolerance for the event. If its a match for more than one, the plate with least distance is chosen.

Regex / String Matching

Each known plate can be associated with a list of regular expressions and/or plain strings, and these will be checked for every discovered licence plate.

Primary Dependencies

  • watchdog - File system monitoring (cross-platform)
  • paho-mqtt - MQTT client
  • Pillow - Image processing
  • pytesseract - OCR for direction detection
  • structlog - Structured logging
  • niquests - API Client
  • requests-cache - API result caching

Distribution

ANPR2MQTT is free and open sourced under the Apache 2.0 license.

Rhizomatics Open Source for Home Assistant

HACS

  • AutoArm - Automatically arm and disarm Home Assistant alarm control panels using physical buttons, presence, calendars, sun and more
  • Remote Logger - OpenTelemetry (OTLP) and Syslog event capture for Home Assistant
  • Supernotify - Unified notification for easy multi-channel messaging, including powerful chime and security camera integration.

Python / Docker

  • Updates2MQTT - Automatically notify via MQTT on Docker image updates, with advanced handling to extract versions and release notes from images, and option to remotely pull and restart containers from Home Assistant. Also available on PyPI

Metadata

Release files for anpr2mqtt 1.1.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for anpr2mqtt 1.1.5
File Size Uploaded Provenance Actions
anpr2mqtt-1.1.5.tar.gz 31.1 kB With provenance Details for anpr2mqtt-1.1.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for anpr2mqtt 1.1.5
File Interpreter ABI Platform Actions
anpr2mqtt-1.1.5-py3-none-any.whl Python 3 none any Details for anpr2mqtt-1.1.5-py3-none-any.whl

Total release size: 65.7 kB

Release files / anpr2mqtt-1.1.5.tar.gz

Download URL anpr2mqtt-1.1.5.tar.gz
Size 31.1 kB
Tags Source
SHA-256 checksum
How to use checksums
b81f8af59755cbef3c00d9e61924733ad923305086f6cb24a9cfea286f296d1b
BLAKE2b-256 checksum
How to use checksums
56e9d7ec6ca39da02c28bfb62308019de2e4fa58b3687fe2be20be431ed7ebda
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.

Transparency log

Release files / anpr2mqtt-1.1.5-py3-none-any.whl

Download URL anpr2mqtt-1.1.5-py3-none-any.whl
Size 34.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e51a7f56d5f38034ecf495e60b3750dcd9589754b85f6e42bd52422978304339
BLAKE2b-256 checksum
How to use checksums
078402039bfa09f25190ac7b679e30f5b039253090818e88bacf22efd280058c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.

Transparency log

Security for anpr2mqtt 1.1.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for anpr2mqtt-1.1.5.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page