🐋 rtl_433 Docker Image

Multi-architecture Docker images for rtl_433 - a generic data receiver for ISM band devices using RTL-SDR and SoapySDR.

Quick Start

# Find your USB device
lsusb | grep RTL

# Run rtl_433 (replace 001/003 with your bus/device)
docker run --device /dev/bus/usb/001/003 hertzg/rtl_433

Tip: Device paths can change on reboot. For stable, persistent identification, use serial number selection instead.

Image Variants

Variant	Base	Size	SDR Support
alpine (default)	Alpine Linux	~3 MB	RTL-SDR
debian	Debian	~50 MB	RTL-SDR + SoapySDR

Image Tags

Images are available from multiple registries:

hertzg/rtl_433:<version>-<base>-<base_version>
hertzg/rtl433:<version>-<base>-<base_version>
ghcr.io/hertzg/rtl_433_docker:<version>-<base>-<base_version>

Available Versions

Only the last 3 releases plus master are built:

Tag	Description
latest	Latest stable release (Alpine)
master	Latest development build
25.12, 25.02, 24.10	Specific releases

Tag Examples

docker run hertzg/rtl_433:latest
docker run hertzg/rtl_433:25.12
docker run hertzg/rtl_433:25.12-alpine
docker run hertzg/rtl_433:25.12-debian-trixie
docker run hertzg/rtl_433:master

Usage

Finding Your USB Device

$ lsusb
Bus 001 Device 003: ID 0bda:2838 Realtek Semiconductor Corp. RTL2838 DVB-T

The device path is /dev/bus/usb/<bus>/<device> → /dev/bus/usb/001/003

Note: Device paths may change on reboot or replug. See #14 for details. For persistent identification, use serial numbers.

Basic Usage

docker run --device /dev/bus/usb/001/003 hertzg/rtl_433

Passing Arguments

Arguments are passed directly to rtl_433:

docker run --device /dev/bus/usb/001/003 hertzg/rtl_433 -V          # version
docker run --device /dev/bus/usb/001/003 hertzg/rtl_433 -F json     # JSON output
docker run --device /dev/bus/usb/001/003 hertzg/rtl_433 -R 40 -R 41 # specific decoders

Stable Device Selection

Device paths like /dev/bus/usb/001/003 can change on reboot or replug. For reliable, persistent device identification, use serial number selection:

# Pass entire USB bus and select by serial
docker run --device /dev/bus/usb hertzg/rtl_433 -d :00000001

This approach:

• Works reliably across reboots
• Handles device re-enumeration automatically
• Is required for multiple RTL-SDR dongles

Finding your serial number:

lsusb -v -d 0bda:2838 2>/dev/null | grep iSerial

Setting a unique serial number:

rtl_eeprom -s 00000001  # Connect one device at a time

See #14, #45, #82 for background.

Custom Config File

Mount your config file into the container (#108, #78):

docker run --device /dev/bus/usb/001/003 \
  -v /path/to/rtl_433.conf:/etc/rtl_433/rtl_433.conf:ro \
  hertzg/rtl_433

Or specify the path explicitly:

docker run --device /dev/bus/usb/001/003 \
  -v /path/to/my.conf:/config/my.conf:ro \
  hertzg/rtl_433 -c /config/my.conf

Timezone

Set the TZ environment variable:

docker run --device /dev/bus/usb/001/003 \
  -e TZ=America/New_York \
  hertzg/rtl_433 -M time:tz

Rootless Operation

For rootless Docker, set up udev rules on the host (#118):

# Download udev rules
sudo curl -o /etc/udev/rules.d/rtl-sdr.rules \
  https://raw.githubusercontent.com/osmocom/rtl-sdr/master/rtl-sdr.rules
sudo udevadm control --reload-rules

# Find plugdev group ID
grep plugdev /etc/group

# Run with group access (replace 46 with your plugdev GID)
docker run --device /dev/bus/usb/001/003 \
  --user "$(id -u):$(id -g)" \
  --group-add 46 \
  hertzg/rtl_433

Examples

MQTT Output

docker run --device /dev/bus/usb/001/003 hertzg/rtl_433 \
  -F mqtt://192.168.1.100:1883

MQTT with Authentication

docker run --device /dev/bus/usb/001/003 hertzg/rtl_433 \
  -F "mqtt://192.168.1.100:1883,user=myuser,pass=mypass"

MQTT + InfluxDB

docker run --device /dev/bus/usb/001/003 hertzg/rtl_433 \
  -M time:unix:usec:utc \
  -F mqtt://192.168.1.100:1883 \
  -F "influx://192.168.1.100:8086/write?db=rtl433"

Docker Compose

services:
  rtl433:
    image: hertzg/rtl_433:latest
    restart: unless-stopped
    devices:
      - /dev/bus/usb  # Pass entire bus for stable device discovery
    environment:
      - TZ=Europe/London
    command:
      - -d :00000001  # Select device by serial (stable across reboots)
      - -M time:unix:usec:utc
      - -M protocol
      - -F mqtt://mosquitto:1883,retain=1
      - -F influx://influxdb:8086/write?db=rtl433

  mosquitto:
    image: eclipse-mosquitto:2

  influxdb:
    image: influxdb:1.8

Note: Using -d :SERIAL with /dev/bus/usb is more reliable than specifying a device path like /dev/bus/usb/001/003, which can change on reboot.

With specific device path (less stable):

services:
  rtl433:
    image: hertzg/rtl_433:latest
    devices:
      - /dev/bus/usb/001/003  # May change on reboot
    command:
      - -F mqtt://mosquitto:1883

Supported Platforms

Architecture	Alpine	Debian	Devices
linux/amd64	✅	✅	x86_64 PCs, servers
linux/arm64	✅	✅	Raspberry Pi 4/5, Apple Silicon
linux/arm/v7	✅	✅	Raspberry Pi 2/3 (32-bit)
linux/arm/v6	✅	❌	Raspberry Pi Zero/1

Troubleshooting

"usb_claim_interface error -6"

Another process is using the device (#33). Unload the kernel driver:

sudo rmmod dvb_usb_rtl28xxu rtl2832

To prevent auto-loading, blacklist the module:

echo "blacklist dvb_usb_rtl28xxu" | sudo tee /etc/modprobe.d/blacklist-rtl.conf

"PLL not locked" (RTL-SDR Blog V4)

The RTL-SDR Blog V4 requires newer drivers not included in the standard image. See #106 for building a custom image.

Device not found

# Verify device exists on host
ls -la /dev/bus/usb/001/003

# Test with privileged mode (debugging only)
docker run --privileged -v /dev/bus/usb:/dev/bus/usb hertzg/rtl_433

Device path changed

Use serial number selection instead of device path (#14):

docker run --device /dev/bus/usb hertzg/rtl_433 -d :YOUR_SERIAL

Links

• rtl_433 GitHub
• rtl_433 Documentation
• Docker Hub
• GitHub Container Registry