Choose your language

Choose your login

Support

Restore the CUPS Web Interface on macOS 27 (localhost:631 Alternative)

This page applies to:

Last updated November 19, 2026

On macOS 27 (Golden Gate), Apple removed the built-in CUPS web interface at http://localhost:631, even if you run cupsctl WebInterface=yes in Terminal. To manage printers, print queues, PPDs, and stuck print jobs in your browser on macOS 27 (or earlier macOS versions), install cups-webui — PaperCut’s free, open-source replacement that runs locally at http://127.0.0.1:6310.

Why is localhost:631 not working on macOS 27?

Starting with macOS 27.0 (Golden Gate), the cupsd web interface is no longer supported. If you’ve found localhost:631 not working in your browser after upgrading, this is why: with the CUPS web interface removed, you can no longer use it for macOS 27 printer admin tasks such as adding, configuring, or sharing printers.

On macOS 26 (Tahoe) and earlier, visiting http://localhost:631 showed “Web interface is currently disabled. Run “cupsctl WebInterface=yes” to enable it.” In macOS 27, running cupsctl WebInterface=yes no longer restores the page—browsers either show that the web interface is disabled or fail with localhost refused to connect (ERR_CONNECTION_REFUSED), and CUPS logs warn that “Printer drivers are deprecated and will stop working in a future version of CUPS.”

Native terminal commands like lpadmin and lpstat are not impacted by this macOS change. To bring back browser-based printer administration on macOS 27 (as well as macOS 26 Tahoe, Sequoia, and Sonoma), PaperCut has built a Web Interface for CUPS (cups-webui), a free, open-source alternative to the legacy CUPS web interface.

What is cups-webui?

cups-webui is a lightweight, single-file replacement for the legacy CUPS web interface on macOS. It runs locally on your Mac at http://127.0.0.1:6310 and manages CUPS through the standard command-line tools (lpadmin, lpstat, lpoptions, cancel and cupsctl).

cups-webui browser interface on macOS showing print queues, Rosetta 2 driver audit, and CUPS settings

With cups-webui you can:

  • Add and configure printers, print queues and printer pools (CUPS classes)
  • View print queues, find stuck print jobs and cancel them with one click
  • Audit printer drivers for Intel-only (x86_64) binaries that rely on Rosetta 2, and inspect /var/log/cups/error_log with plain-English remedies for Filter failed errors
  • Manage printers without running cupsctl WebInterface=yes in Terminal
  • Use a modern dashboard with light and dark modes

cups-webui is a universal binary that runs on both Apple Silicon and Intel Macs, with nothing else to install.

Feature Legacy CUPS (localhost:631) cups-webui (127.0.0.1:6310) Terminal (lpadmin / lpstat)
Works on macOS 27+ No (Removed by Apple) Yes (macOS 27 & earlier) Yes
Requires cupsctl WebInterface=yes Yes No No
Add / Edit Queues, PPDs & Default Options Yes (macOS 26 & older) Yes (Browser UI) Manual CLI flags
Rosetta 2 / Intel (x86_64) Driver Audit No Yes (Built-in Mach-O scanner) Manual file / lipo
Plain-English /var/log/cups/error_log Diagnostics No Yes (Filter failed remedies) Manual log reading
License & Cost Built-in (Deprecated) Free & Open Source (MIT) Built-in

Is cups-webui free and open source?

Yes. cups-webui is open source and free to use under the MIT License. You can view the source code, report issues and contribute improvements on GitHub. Pull requests are welcome.

In line with the MIT License, the software is provided “as is”, without warranty of any kind. We recommend reviewing and testing it in your own environment before rolling it out widely.

Is cups-webui secure?

cups-webui only listens on your Mac’s loopback address (127.0.0.1), so it can’t be reached from other computers on your network. It automatically signs in only the macOS user account that started it; other accounts on the same Mac are not signed in. It also includes protections against malicious websites and command injection. For full details, see the cups-webui security model.

Please report suspected vulnerabilities through PaperCut’s security contact page, not as public GitHub issues.

How to restore the CUPS web interface on macOS 27

Download cups-webui (or browse the cups-webui GitHub repository) to restore web-based CUPS management. Once downloaded, follow these steps to install and run the interface:

  1. Make the file executable: Open Terminal, go to the folder you downloaded the file to (for example, cd ~/Downloads), and run chmod +x cups-webui. If macOS later says the file can’t be opened because it was downloaded from the internet, run xattr -d com.apple.quarantine cups-webui, or allow it in System Settings → Privacy & Security.
  2. Launch the interface: Run ./cups-webui -open to start the server and open the interface in your default browser. The interface runs locally at http://127.0.0.1:6310. Once the server is running, you can open (or bookmark) that address directly. This runs until you close Terminal. To keep it running and start it at every login, see step 3. No login is needed for the user account that runs the server; other accounts on the same Mac are not signed in.
  3. Set up Auto-Start on macOS Login (Recommended): Run ./cups-webui launchagent install once. cups-webui then starts automatically every time you log in, with no other setup needed. Clicking CUPS Settings → Enable Auto-Start in the web interface does the same thing, so use whichever is easier. It starts at login (not when the Mac boots) and only for your user account.
    • Option A (Web UI): Click CUPS Settings → Enable Auto-Start.
    • Option B (CLI): Run ./cups-webui launchagent install. This copies the binary to ~/Library/Application Support/cups-webui/, registers it with launchd, and starts the service straight away (or upgrades an existing service in place). From then on it also starts automatically at every login. Then open http://127.0.0.1:6310 in your browser and bookmark it. To check that the service is running, use ./cups-webui launchagent status.

Quick Terminal one-liner (download, install as a service that starts automatically at login, and open):

curl -fsSL https://github.com/PaperCutSoftware/cups-web-interface/raw/main/bin/cups-webui -o cups-webui \
  && chmod +x cups-webui \
  && xattr -d com.apple.quarantine cups-webui 2>/dev/null || true \
  && ./cups-webui launchagent install \
  && ./cups-webui open

To try cups-webui with simulated printers and queues before using it on real printers, run ./cups-webui -mock -open.

How to uninstall cups-webui

  1. If you installed the background service (with launchagent install or Enable Auto-Start), run ./cups-webui launchagent uninstall. It stops the service, and it no longer starts at login.
  2. Delete the downloaded cups-webui file and the ~/Library/Application Support/cups-webui/ folder.
  3. Delete the ~/.cups-webui/ folder, which holds the saved sign-in session.

Prefer the command line?

The CUPS command-line tools still work in macOS 27. Some common printer admin commands (replace Office_Printer and the address with your own; some commands need an administrator account):

  • List printers and their status: lpstat -p
  • Add a network printer using IPP Everywhere: lpadmin -p Office_Printer -E -v ipp://192.168.1.50/ipp/print -m everywhere
  • Set your default printer: lpoptions -d Office_Printer
  • Cancel all jobs on a printer: cancel -a Office_Printer
  • Remove a printer: lpadmin -x Office_Printer

Troubleshooting

  • macOS won’t open the file: Remove the download quarantine with xattr -d com.apple.quarantine cups-webui, or allow it in System Settings → Privacy & Security.
  • The browser doesn’t open: Go to http://127.0.0.1:6310 manually, or run ./cups-webui open.
  • Port 6310 is already in use: cups-webui may already be running, for example as the auto-start service. Open http://127.0.0.1:6310 to check. To use a different port, start it with -port, for example ./cups-webui -port 6320 -open.

FAQ

Why can’t I open localhost:631 on macOS 27?

The CUPS web interface is no longer supported in macOS 27. Printing and the CUPS command-line tools still work; only the browser-based admin page is gone. cups-webui provides a replacement at http://127.0.0.1:6310.

Do I need to run cupsctl WebInterface=yes?

No. cups-webui works without enabling the legacy CUPS web interface.

Does cups-webui start automatically when I log in?

Yes, if you installed it with ./cups-webui launchagent install (or the one-liner), or clicked Enable Auto-Start in CUPS Settings. Both do the same thing. Running ./cups-webui -open on its own does not start it at login.

Does cups-webui work on Apple Silicon and Intel Macs?

Yes. It’s a universal binary for both.

Is cups-webui free?

Yes. It’s open source under the MIT License and free to use, without warranty.

How do I report a bug or suggest an improvement?

Open an issue or pull request on GitHub. Report security issues through PaperCut’s security contact page.


Category: Reference Articles

Subcategory: Installing, Uninstalling and Migrating


Keywords: localhost:631, cupsctl WebInterface=yes, macOS 27 CUPS web interface, cups-webui, Web interface is currently disabled, macOS printer administration, Rosetta 2 printer driver audit

Comments

Comments are not available in this preview environment. On papercut.com, this space shows the live Disqus comment thread for this page.