Printing and Scanning
LuxOS sets up USB printers and scanners without asking. A new printer on the network is offered in
a notification ("Printer “X” found on the network" with Add) and gets a queue only after you
click Add. Drivers are not needed where possible (IPP Everywhere / AirPrint / Mopria, and ipp-usb for
USB). Classic USB printers get the best installed driver. Scanners work through SANE with eSCL
(sane-airscan). All of this is in the package luxos-printing, which also provides the apps
Printers & Scanners (luxos-printers) and Scanner (luxos-scan).
Components
| Part | Path | Role |
|---|---|---|
| CUPS | cups.socket |
print server, started on first use |
| Avahi + nss-mdns | avahi-daemon.service |
finds network printers and scanners; .local names |
| ipp-usb | started by udev | makes IPP-over-USB printers look like network printers |
| watcher | luxos-printing-watch.service → /usr/lib/luxos/printing/luxos-printing-watch |
listens to avahi-browse for new _ipp._tcp and _uscan._tcp services and runs the helper; every 30 s runs luxos-printing-helper autoresume, but only while CUPS is running or a queue is stopped |
| USB trigger | /usr/lib/udev/rules.d/99-zz-luxos-printing.rules → luxos-printing-sync.service |
runs the helper when a USB printer or scanner is plugged in |
| helper (root) | /usr/lib/luxos/printing/luxos-printing-helper |
creates the queues and installs drivers |
| admin entry | /usr/lib/luxos/printing/luxos-printing-admin |
the same helper for removing a queue and cancelling another user's job |
| notifications | /usr/lib/luxos/printing/luxos-printing-notify |
"Printer “X” is ready" etc. in the user session |
| mDNS in nsswitch | /usr/lib/luxos/printing/luxos-nsswitch-mdns (+ libalpm hook) |
adds mdns_minimal to the hosts: line of /etc/nsswitch.conf |
| polkit | org.luxos.printing.manage |
lets the active user run the helper through pkexec without a password (add, default, resume, discover) |
| polkit | org.luxos.printing.admin |
removing a printer and cancelling another user's job ask for an administrator password (auth_admin_keep, remembered for a few minutes) |
The package's install script enables cups.socket, avahi-daemon.service and
luxos-printing-watch.service. The print-queue applet (system-config-printer-applet) is disabled
on purpose.
How printers are added
luxos-printing-helper sync finds devices and handles each kind like this:
- Network or IPP-USB printers with driverless support get a queue with
lpadmin -m everywhere. IPP-USB printers (plugged in) are added right away. A network printer is only offered in a notification with Add (luxos-printing-helper add KEY), once per printer: anyone on the same network (also in a café or hotel) can announce a printer, so no queue and no default printer is created without your click. Queues are not shared. mDNS announcements are not authenticated, so everything from them is checked first: only_ipp/_ippsservices in thelocaldomain, DNS-SD names up to 63 bytes without control characters, theUUIDonly in UUID format (anything else is dropped, never put into thednssd://URI), the queue URI must have exactly thednssd://NAME._ipp._tcp.local/?uuid=…shape. At most 5 network printers are offered per hour; others can be added with + in Printers & Scanners. The watcher runssyncat most every 10 seconds, also when the network floods it with announcements. Drivers are never installed because of a network announcement - only for USB printers. Network queues useprinter-error-policy=retry-job, USB queues (classic and IPP-USB)retry-current-job(see Printer unplugged or turned off). - Classic USB printers get the best matching installed PPD driver. If none fits, the helper
installs
hplip(HP) orgutenprint(others) throughlux(lux_alpm.py; it waits if the package database is busy). If that is not possible either, it uses a generic PostScript or PCL driver. - Printers that need a manufacturer driver (Samsung SPL/QPDL lasers such as the Xpress
M2020/M2026, Brother, Canon UFR II, Epson inkjets) get it from the repository
[luxos-drivers]: verified driver packages built by LuxOS from the AUR (see Verified drivers). The helper looks the printer model up in/usr/share/luxos/drivers-index.json(packageluxos-drivers-index, installed by the helper when missing;luxos_printing.verified_driver), installs the driver as root throughluxand creates the queue - no AUR build, no password. The Samsung PPD is per series ("M2020 Series" covers M2026). - Only when the driver is not in the configured repositories (old
lux.confwithout[luxos-drivers], or the repository database not downloaded yet) the printer gets no queue and the notification "needs a driver from the manufacturer" has an Install Driver button: it opens Terminal withlux install samsung-unified-driver-printerand then runspkexec luxos-printing-helper sync. "Add" in Printers & Scanners offers the same. - Some HP models need HP's proprietary plugin. The notification then says: "Open Terminal and run: hp-plugin".
- A network printer without driverless support gets no queue automatically. The notification says "needs to be set up… Open Printers & Scanners and choose Advanced…".
- With no internet, a needed driver is installed later ("LuxOS will set it up automatically once you are connected to the internet").
The helper remembers the queues it created in /var/lib/luxos-printing/state.json. It never
touches queues created by someone else, and it does not re-add a printer you removed.
Other helper commands (root, or through pkexec):
luxos-printing-helper discover # JSON of all found printers
luxos-printing-helper add KEY # add one from discover (also a removed one)
luxos-printing-helper remove QUEUE # remove (and do not add again) - via pkexec only luxos-printing-admin
luxos-printing-helper default QUEUE # default printer
luxos-printing-helper resume QUEUE # re-enable a paused queue
luxos-printing-helper cancel ID # cancel a print job (any user) - via pkexec only luxos-printing-admin
luxos-printing-helper autoresume # resume queues paused because the printer was away (watcher)
luxos-printing-helper migrate # one-time error policy update of older queues (package upgrade)
Printer unplugged or turned off
A document printed while the printer is off or unplugged waits and prints by itself as soon as the printer is back - no button to press.
- Error policy. CUPS (and Arch) default to
stop-printer: after any backend error the queue is stopped and never started again by CUPS itself. USB queues created by LuxOS useretry-current-job: when the cable is pulled or the printer is turned off during a job, the job starts again at once and the CUPSusbbackend waits for the printer ("Waiting for printer to become available").retry-jobis not used for USB because CUPS discards the job afterJobRetryLimit(5) ×JobRetryInterval(300 s). Network queues keepretry-job: theippbackend already waits for a printer that is off (up to 7 days), so a failure there is a real printer error and the limited retries cannot loop forever. - Migration. On upgrade (
luxos-printing-helper migrate, otherwise at the first check) LuxOS setsretry-current-jobonce on its own USB queues and on USB queues created by another tool that still have the CUPS defaultstop-printer. A policy someone chose (for exampleabort-job) is kept. The state ispolicy_versionin/var/lib/luxos-printing/state.json. - Paused queues are resumed automatically. A queue can still be stopped: by CUPS when the
backend reports a fatal error ("Printer stopped due to backend errors", "unrecoverable USB error")
or, on older installs, by system-config-printer's
udev-configure-printerwhen the printer was unplugged ("Unplugged or turned off"; LuxOS masks its udev rule, which also removed the part that re-enabled the queue).luxos-printing-helper autoresumerunscupsenable(andcupsaccept) for such queues as soon as their printer is present, and releases jobs held because the printer was unavailable. It runs after everysync(a USB printer plugged in, a network or IPP-USB printer announced by Avahi), at start and every 30 s from the watcher. - USB: the serial number from the queue's
usb://…?serial=URI is matched against/sys/bus/usb/devices(printer interface class 07); without a serial numberlpinfodecides. Network and IPP-USB: the service (UUID or name) must be visible in Avahi. - Only queues stopped because the printer was missing are resumed. A queue paused by you ("Paused" or your own reason) stays paused - use Resume.
- If CUPS stops the queue again right away (for example a broken driver), the next attempt waits 5, 10, 20 … minutes (at most 6 hours).
- The watcher does not wake CUPS: when
cups.serviceis not running there are no jobs, and it only reads/etc/cups/printers.confuntil a stopped queue's printer is actually back. - Notifications. When a document waits for a printer that is not connected, a short notification
says "Printer “X” is not connected – Connect the USB cable or turn the printer on. The document
will print automatically." (for a network printer: turn it on and connect it to the same network).
It is a status message (
transienthint) and does not stay in the bell. Only when the document is still waiting after 5 minutes does one more notification stay in the bell ("A document is waiting for printer “X”"). When a paused queue is resumed with documents waiting: "Printer “X” is connected again – Waiting documents are printing now."
Printers & Scanners app
Run luxos-printers (or luxos-printers --add to open Add Printer, --scanner to select the
first scanner). It is in Launchpad and Settings.
- Printers list with state: Ready, Printing…, N documents waiting, Paused, "Not connected"
for a network printer that is not reachable now (turned off or on another network; with
"· N documents waiting" when documents wait), "Not connected – connect the USB cable or turn the
printer on" (USB; checked every 2 s in sysfs) and, when documents wait or the queue was paused
because the USB printer was away, "… Documents will print automatically." (the job then shows
"Waiting for the printer" instead of "Printing…"). A network printer counts as reachable only
when it is announced on the network (mDNS) and answers a short connection to its address
(
ipp://,ipps://,socket://queues: the address and port from the URI); this is checked off the main thread every 12 s while the window is open and right after a network change - CUPS alone reports a driverless queue as ready until a job fails. Ink and toner levels, and the print queue with per-job Cancel and Cancel All. - Per-printer actions: Default printer, Print Test Page, Resume (only when the printer is paused for another reason than being unplugged or turned off - that resumes by itself), Remove Printer….
- Add Printer… is a fallback for when the printer was not added automatically. It shows
"Printers nearby" (USB and network) with an Add button. Advanced… opens
system-config-printerfor printers that need special setup (LPD, Windows sharing, manual drivers). - Scanners tab: Kind, Quality, Source, Preview, Scan. It saves as a PDF document or JPEG pictures and supports several pages.
Scanner app
Run luxos-scan (optionally --device <SANE device>). It is a simple scanner with one Scan button.
- The scanner is picked automatically. A list appears only when there are several. eSCL is preferred over WSD when the same scanner shows up through several backends.
- Scan as Document (300 dpi) or Photo (600 dpi). Colours: Colour or Black & white. Paper size. Source: Glass (flatbed), Document feeder, or Document feeder, both sides.
- Pages can be reordered and removed, and "Scan Another Page" adds more. Save as a PDF document (multi-page), JPEG picture or PNG picture, or Print….
- Files are named like
Scan 2026-10-22 14.03and saved to the Documents folder (xdg-user-dir DOCUMENTS, otherwise~/Documents). Temporary pages are kept in~/.cache/luxos-scan. - Scanning runs
scanimagein a background thread. Cancel sends SIGTERM. - The laptop camera (SANE
v4lbackend) is never listed as a scanner. - With no scanner found the app keeps looking every few seconds, so a scanner switched on later appears by itself. The refresh button in the title bar searches again at any time.
Troubleshooting
- Printer not added: make sure it is on and on the same network. Open Printers & Scanners ›
Add Printer… › Search Again. Check the services:
systemctl status cups.socket avahi-daemon luxos-printing-watch, and the log:journalctl -u luxos-printing-watch -u luxos-printing-sync. - See what the system finds:
avahi-browse -rt _ipp._tcp(network printers),lpstat -v(queues),pkexec /usr/lib/luxos/printing/luxos-printing-helper discover. .localnames do not resolve: thehosts:line of/etc/nsswitch.confmust containmdns_minimal. Repair (root):/usr/lib/luxos/printing/luxos-nsswitch-mdns.- Printer "needs a driver": connect to the internet. The helper installs
hpliporgutenprintitself. You can also install them by hand:lux install hplip. - HP printer needs a plugin: run
hp-pluginin a terminal. - Printer not driverless (old network printer): use Advanced… (system-config-printer).
- Paused printer: a printer paused because it was unplugged or off resumes by itself when it
is connected again (log:
journalctl -u luxos-printing-watch -u luxos-printing-sync, "queue resumed"). Otherwise the Resume button in the app, orluxos-printing-helper resume QUEUE. - "Not connected" although the cable is in:
lsusbmust list the printer; if it does not, try another cable or USB port, and turn the printer off and on. - Scanner not found:
scanimage -L. The Scanner app says "Scanning support is not installed" when SANE is missing (installluxos-printing). It says "The scanner does not respond" when the device is off or busy. - The LuxOS firewall lets printer and scanner discovery through (mDNS, SSDP, WS-Discovery, SNMP, Canon BJNP and Epson replies from this network) and printing itself is an outgoing connection. Sharing your printers with other computers opens TCP 631 automatically once CUPS shares them. See firewall.md.