Web interface for CUPS: a modern, lightweight, single-binary replacement for the legacy CUPS web interface (localhost:631) on macOS.
Designed specifically to address UX barriers in macOS and UNIX environments:
- Zero Configuration Access: Bypasses the requirement to run
cupsctl WebInterface=yesin Terminal. - Human-Centric UX: Replaces technical abstractions (PPDs, Classes) with clear workflows (Printers, Print Queues, Printer Pools).
- Modern Responsive Interface: Clean dashboard that follows your Mac's light or dark appearance, built with Tailwind CSS and Lucide icons.
- Queue Diagnostics & Stuck Job Remediation: Identifies stuck print jobs and provides instant one-click cancellation.
- Security-First: Binds to loopback
127.0.0.1:6310by default, and signs in only the macOS user who runs it. See SECURITY.md.
A pre-compiled universal binary for macOS (supporting both Apple Silicon and Intel) is included directly in bin/cups-webui, so you can run the app immediately without installing Go or Node.js.
Start the server and automatically open the interface in your browser:
./bin/cups-webui -openThe interface will be available at http://127.0.0.1:6310. Once the server is running, you can open (or bookmark) that address directly; no login step is needed for the user account that runs the server. Other accounts on the same Mac are not signed in.
This runs until you close the Terminal window. To keep it running and start it at every login, see step 2.
Running the install command is all you need. It sets up cups-webui as a background service (a macOS LaunchAgent) that starts every time you log in and restarts if it stops. You don't need to enable anything else in the web interface.
# Install the service: it starts now and at every login
./bin/cups-webui launchagent install
# Or install it on a different port
./bin/cups-webui launchagent install -port 8631
# Check service status
./bin/cups-webui launchagent status
# Remove the service (it stops and no longer starts at login)
./bin/cups-webui launchagent uninstallThe install command copies the binary to ~/Library/Application Support/cups-webui/ and starts the service straight away. Open http://127.0.0.1:6310 in your browser and bookmark it (or the port you chose with -port).
Enable Auto-Start under CUPS Settings in the web interface does the same thing, so use whichever is easier. It uses the port that instance is running on. Running ./bin/cups-webui -open on its own (step 1) does not start it at login.
The service starts when you log in, not when the Mac boots, and only for your user account.
Runs with simulated printers, queues, and diagnostic alerts without requiring active printer hardware:
./bin/cups-webui -mock -openA driver usually detects a printer's accessories (trays, stapler, hole punch, duplexer) only when the queue is added, and some drivers ask the printer over SNMP. When the queue points at an IPP server such as PaperCut Mobility Print, the Mac can't reach the printer, so those accessories stay "not installed" and features like stapling are unavailable.
The Hardware Accessories tab lists the queue's installable options, installed ones first, and marks values that differ from the driver's default as Detected or Set manually. CUPS administrators can click Edit accessories (Advanced) to change them. Saving does the same as lpadmin -p <queue> -o <Option>=<Choice>: it updates only that queue's PPD, never the shared driver PPD. The app then reads the PPD back from CUPS and shows what was stored.
- These settings can't be checked against the printer. Confirm the printer has the hardware first. The warning is stronger when the queue doesn't point straight at the printer.
- The value itself is stored by CUPS in the queue's PPD. Who set it, when, and the value it replaced are notes kept by this app in
~/.cups-webui/accessory-overrides.json. Reset to detected values puts the old values back. - The notes belong to the macOS account running the service and stay on this Mac: another admin account, or a copy of the queue on another Mac, doesn't see them. "Set by" is that account's name, and the file can be edited by it, so treat the notes as a reminder, not an audit log. For a record of who changed a queue, see CUPS's own log (
/var/log/cups/access_log). - Notes are tied to the queue's CUPS identity (
printer-uuid), so a queue deleted and re-created with the same name doesn't inherit them. Notes for deleted queues are removed. If the notes file is damaged or was written by a newer version of the app, the tab still shows the values from CUPS, but changes are refused until the file is fixed. - If the queue's driver is replaced from the app, manual values are applied again.
- For drivers in a small built-in table (currently "Generic Universal Mono"), Ask the device for suggestions reads the device's IPP attributes and fills in the form. Nothing is saved until you confirm.
- The section isn't shown for driverless (AirPrint / IPP Everywhere) queues or for drivers without installable options.
| Flag | Default | Description |
|---|---|---|
-port |
6310 |
Port to listen on |
-host |
127.0.0.1 |
Host interface to bind to. Only loopback is supported |
-mock |
false |
Run with simulated CUPS mock data |
-open |
false |
Automatically open default browser on launch |
Subcommands:
cups-webui open– Open the running server in your default browser using its session linkcups-webui launchagent [install|uninstall|status]– Manage the macOS background LaunchAgent service
If you would like to build or modify the project yourself:
The Go code uses only the standard library, so go.mod lists no dependencies and there is no go.sum file.
# Build the frontend SPA and compile the universal macOS binary (bin/cups-webui):
make build
# Or compile only the native Go binary for your current machine architecture:
make build-go
# Or build the frontend independently:
cd web && npm install && npm run buildRun the Go test suite:
make test- Backend (
cmd/cups-webui/main.go,internal/api/,internal/cups/): Pure Go, standard library only, usingnet/httpand the native CUPS command-line tools (lpstat,lpadmin,lpoptions,cancel,cupsctl,cupsdisable,cupsenable). - Frontend (
web/): React 19 + TypeScript + Tailwind CSS v4 SPA, compiled directly intointernal/web/distand embedded into the Go binary withgo:embed. - Packaging: Single executable (
./bin/cups-webui) with zero runtime dependencies.
The security model is described in SECURITY.md. Please report suspected vulnerabilities through https://www.papercut.com/contact/security/ and not as public issues.
MIT. See LICENSE. Bundled fonts are covered by their own licences; see THIRD_PARTY_NOTICES.md.
CUPS WebUI (cups-webui) is an open-source project actively maintained by PaperCut Software, makers of print management software. It was built after Apple decided to remove the built-in CUPS Web Interface (localhost:631) in macOS 27 Golden Gate. Although admins can still use commands like lpadmin and lpstat to manage print queues and default settings, cups-webui offers a much easier way to manage them.
