Home Assistant OS CUPS AirPrint Add‑on

CUPS + AirPrint print server for Home Assistant OS

This add‑on allows you to run a CUPS (Common Unix Printing System) server with AirPrint support inside Home Assistant OS using the Supervisor add‑on system.

It enables local network printing from devices (PCs, phones, tablets) including AirPrint (iOS/macOS) compatible printing through Bonjour/Avahi.

CUPS is the standard Unix printing system used on most Linux systems and can share printers over IPP, including support for legacy and non‑AirPrint printers, once configured properly.

---

📌 Features

• Runs CUPS print server inside Home Assistant OS
• AirPrint support via Avahi/mDNS
• Share USB or network printers
• Bonjour/Avahi advertising for Apple devices
• Web admin interface via CUPS
• Works with non‑AirPrint capable printers

---

🚀 Installation

• Open Home Assistant
• Go to Settings → Add‑ons → Add‑on Store
• Click ⋮ (top right) → Repositories
• Add this repository URL
• Install CUPS AirPrint Add‑on
• Start the add‑on
• (Optional) Enable Start on boot and Watchdog

---

⚙️ Configuration

Example (config.yaml):

admin_username: admin
admin_password: your_password
printer_share: true

• admin_username – username for CUPS admin interface
• admin_password – password for CUPS admin
• printer_share – whether to auto‑share printers via CUPS You may also configure Avahi/Bonjour settings if supported by the add‑on.

---

🖨️ How It Works

• CUPS runs inside the add‑on and listens for print jobs
• Printers are configured via the CUPS web UI (http://<HA_IP>:631)
• Avahi advertises shared printers over mDNS/Bonjour
• AirPrint devices (iOS, macOS) discover printers automatically
• Devices can send print jobs using AirPrint or standard IPP AirPrint is Apple’s network printing protocol, allowing iOS and macOS devices to print without additional drivers.

---

🛠 Tips

• Make sure your printer drivers are installed or available to CUPS
• Enable “Share This Printer” in the CUPS admin UI
• Some networks require multicast for AirPrint/Bonjour discovery
• Restart the add‑on after making changes to printer configs

---

🔐 Accessing the CUPS Admin Interface

After installing and starting the add‑on:

• Visit the CUPS admin at: http://<your_home_assistant_ip>:631
• Log in using admin_username and admin_password set in config Here you can add printers and set sharing options.

---

🛡️ Security

• Use a secure password for admin access
• Ensure your network firewall allows access only where needed
• Avoid exposing CUPS admin to untrusted networks

---

🧱 Requirements

• Home Assistant OS or Supervised
• Supervisor enabled
• Printer connected via USB or network
• mDNS/Bonjour support for AirPrint to work

homeassistant addon cups airprint

CUPS addon with working Avahi in reflector mode

Tested with Home Assistant version 2025.2.3

CUPS administrator login: print, password: print (can be changed in the Dockerfile)

Configuration data is stored in /addon_configs/_cups folder