Sign inSign up

jdrtronix/cups-hplip

By jdrtronix

•Updated 6 months ago

CUPS print & scan server with HP HPLIP plugin, AirSane eSCL, and SANE network support.

Image
Networking
2

7.3K

jdrtronix/cups-hplip repository overview

⁠cups-hplip

A ready-to-run CUPS print and scan server with full HP printer support via the proprietary HPLIP plugin. Built for home lab and small office use.

⁠Features
  • Print from Windows, macOS, and Linux via IPP/IPPS
  • Scan from Windows via NAPS2 (eSCL on port 8090)
  • Scan from Linux via SANE network protocol (port 6566)
  • HP proprietary plugin pre-installed (required for many modern HP printers)
  • Auto-detects scanner when printer is powered on (via host udev rule)
  • Self-signed SSL certificate auto-generated on first start
  • Based on Debian 13 slim
⁠Quick Start

1. Create config directories

mkdir -p /opt/cups/config /opt/cups/sane
2. docker-compose.yml


services:
  cups:
    image: jdrtronix/cups-hplip:latest
    container_name: cups
    restart: unless-stopped
    privileged: true
    network_mode: host
    volumes:
      - /opt/cups/config:/etc/cups
      - /opt/cups/sane:/etc/sane.d
    devices:
      - /dev/bus/usb:/dev/bus/usb
3. Start


docker compose up -d
CUPS web UI: http://<host-ip>:631

Adding a Printer
Open http://<host-ip>:631
Go to Administration → Add Printer
Select your HP USB printer and follow the steps
Windows — Printing via IPP
Settings → Bluetooth & devices → Printers & scanners → Add device → Add manually
Select Add a printer using an IP address or hostname
Protocol: IPP · Address: <host-ip> · Port: 631
Resource: /printers/<printer-name>
Windows — Scanning via NAPS2
NAPS2 is a free open-source scanning app with eSCL support.

Download and install NAPS2
Open NAPS2 → Devices → Add Device
Driver: ESCL → click Manual IP
IP/Host: <host-ip> · Port: 8090 · HTTPS: off
Click Connect
Auto-restart on Printer Power Cycle
When the printer is powered off and back on, it gets a new USB device number.
A udev rule on the host restarts the container automatically.

Find your printer's USB Product ID:


lsusb | grep -i hp
# e.g. ID 03f0:042a HP, Inc LaserJet M1132 MFP
Alpine Linux — install eudev first:


apk add eudev
rc-update add udev sysinit && rc-service udev start
Create the udev rule (replace 042a with your printer's product ID):


mkdir -p /etc/udev/rules.d
cat > /etc/udev/rules.d/99-hp-printer.rules << 'EOF'
ACTION=="add", SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="03f0", ATTR{idProduct}=="042a", RUN+="/usr/bin/docker restart cups"
EOF
udevadm control --reload-rules
Allow Network Scanning (SANE)
Edit /opt/cups/sane/saned.conf and add your subnet:


10.9.8.0/24
localhost
Then restart the container.

Tested Hardware
HP LaserJet M1132 MFP
Other HP printers requiring the HPLIP plugin should work.
Check the HPLIP supported devices list.

Ports
Port	Purpose
631	CUPS web UI + IPP printing
8443	CUPS over SSL (IPPS)
6566	SANE network scanning
8090	AirSane eSCL scanning (NAPS2)
Source
github.com/jdrtronix/cups-hplip

Tag summary

Content type

Image

Digest

sha256:359bc2345…

Size

164.1 MB

Last updated

6 months ago

docker pull jdrtronix/cups-hplip