This Home Assistant app 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 → Apps → Install App.
- 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" app 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 → Apps → Install App.
-
Click the 3-dot menu (top right) → Repositories.
-
Add
/addonsas a repository URL and click Add. -
Refresh the app store to see "CUPS Print Server."
-
Install the app.
The app 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 app 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 app 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 app 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 app.
- Check CUPS logs in the app'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 app settings.
- If you've forgotten your password, you can reset it by reconfiguring the app.
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 app stores all CUPS data in the Home Assistant /data directory, ensuring:
- Printer configurations persist across app restarts
- Print jobs and settings are maintained through system reboots
- App 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