This Home Assistant add-on provides a CUPS (Common Unix Printing System) print server, allowing you to manage and share printers over your local network. It's designed for Home Assistant users who want to integrate network printing capabilities directly into their smart home setup.
- Network Printing: Share printers across your local network using CUPS
- Web Interface: Access the CUPS administration panel at
http://<your-ha-ip>:631to add and manage printers - Secure Administration: Optional authentication for the CUPS admin interface
- Printer Support: Compatible with a wide range of network and USB printers
- Lightweight: Built on Alpine Linux for minimal resource usage
- Data Persistence: Printer settings and configurations persist across restarts and updates
- Navigate to your Home Assistant instance.
- Go to Settings → Add-ons → Add-on Store.
- Click the 3-dot menu in the top right corner and select Repositories.
- Add
https://github.com/arest/cups-addonas a repository. - Find the "CUPS Print Server" add-on in the store and click it.
- Click Install.
If you prefer to manually install:
-
Clone this repository to your local machine:
git clone https://github.com/arest/cups-addon.git
-
Copy the repository to your Home Assistant add-ons directory:
scp -r cups-addon/cups root@<your-ha-ip>:/addons/
-
In Home Assistant, go to Settings → Add-ons → Add-on Store.
-
Click the 3-dot menu (top right) → Repositories.
-
Add
/addonsas a repository URL and click Add. -
Refresh the add-on store to see "CUPS Print Server."
-
Install the add-on.
The add-on provides the following configuration options:
admin_username: printadmin
admin_password: your_secure_password- admin_username: Username for the CUPS admin interface (default: printadmin)
- admin_password: Password for the CUPS admin interface
After configuring:
- Start the add-on from the Info tab.
- Check the Log tab to ensure it starts successfully.
- Access the CUPS web interface at
http://<your-ha-ip>:631.
Visit http://<your-ha-ip>:631 in your browser.
- Go to the Administration tab.
- Click Add Printer and follow the prompts.
- Select the appropriate driver for your printer model.
Configure your computers or devices to use the printer at <your-ha-ip>:631.
This add-on supports various printer types:
- Network printers (via IPP, LPD, etc.)
- USB printers connected to your Home Assistant host
- Shared Windows printers (via Samba)
- AirPrint for Apple devices
- Ensure the add-on is running (check logs).
- Verify port 631 isn't blocked by your firewall.
- Check that your network allows access to the Home Assistant device.
- Ensure the printer is network-accessible or connected via USB to the host.
- For USB printers, you may need to configure USB device pass-through to the add-on.
- Check CUPS logs in the add-on's Log tab.
https://www.openprinting.org/download/PPD/ https://www.openprinting.org/drivers/
- Verify you're using the correct username and password configured in the add-on settings.
- If you've forgotten your password, you can reset it by reconfiguring the add-on.
Contributions are welcome! Please:
- Fork this repository.
- Create a feature branch (
git checkout -b feature/your-feature). - Commit your changes (
git commit -m "Add your feature"). - Push to the branch (
git push origin feature/your-feature). - Open a pull request.
This project is licensed under the MIT License.
- Built by Andrea Restello
- Powered by Home Assistant and CUPS
This add-on stores all CUPS data in the Home Assistant /data directory, ensuring:
- Printer configurations persist across add-on restarts
- Print jobs and settings are maintained through system reboots
- Add-on updates won't cause loss of printer configurations
- All CUPS data is included in Home Assistant backups
The following directories are maintained in the persistent storage:
/data/cups/config: CUPS configuration files/data/cups/cache: CUPS cache data/data/cups/logs: CUPS log files/data/cups/state: CUPS state information