Print Server
There are several steps to get a print server connected in ERPNext.
- First, the
pycupsdependency needs to be installed on the system, which in turn depends on the CUPS project'slibcupslibrary. See the following links for installation instructions:
- OpenPrinting CUPS installation and configuration instructions
- PyCUPS dependencies, compiling, and installation information
- Add the bench user to the
lpadmingroup when administering a local CUPS server:sudo usermod -aG lpadmin {username}. Use Server IPlocalhost(not127.0.0.1) so BEAM uses the CUPS Unix socket and admin operations work without HTTP authentication errors. - Add a network printer using the Network Printer Settings wizard (New opens a guided setup). The Stock Manager at Ambrosia Pie Company can register a ZD621 on the Chelsea receiving dock when Chelsea Fruit Co deliveries arrive — without opening the CUPS web UI. Administrator can repeat the wizard during go-live or link a queue that already exists on CUPS (for example
vRAW). - The wizard walks through print server connection, discovery, queue details, and driver selection. Discovery shows network printers and existing CUPS queues, sorted with unconfigured entries first. Use Test Connection on the discovery and details steps to ping the host and verify the device URI before creating the queue. USB printers are not supported.

The friendly Network Printer Settings name (for example Chelsea Receiving Labels) is separate from the CUPS queue name (for example ZD621). The Printer Name field on the full form is an autocomplete that queries the configured CUPS server and displays available printers by their CUPS identifier, with the physical Printer Location and make/model shown as secondary text (location first when set). Selecting a printer automatically fills in Printer Location from CUPS. The location can be edited freely — saving the record pushes the updated value back to CUPS, keeping the two in sync. Printer Location also appears in the list view for fleet management. The Printer Type field (General Purpose or Label / RAW) distinguishes PDF printers from ZPL/raw label printers.
Saved records show a live CUPS status panel (idle/processing/offline indicator, make/model, CUPS description, accepting jobs).
On a saved record, Administrator can use:
| Action | Purpose |
|---|---|
| Configure Printer | Change device URI, driver (PPD), location, enabled state, and accepting jobs |
| Sync from CUPS | Pull the latest location and device URI from the print server |
| Print Test | Submit a ZPL test label for Label / RAW queues, or a CUPS/text test for General Purpose |
| Printer Options | View and set CUPS driver defaults (General Purpose only) |
| Ping Printer | Ping the host extracted from the device URI |
| Delete from CUPS | Remove the queue and ERPNext record when decommissioning hardware |
Use the Printer Fleet Status report to compare CUPS queues against ERPNext records (synced, orphan, missing, mismatch) across print servers.
Testing (CUPS container)
Integration tests use the CUPS service container from the pytest workflow (no testcontainers):
pytest beam/beam/tests/test_printer_logic.py
pytest beam/beam/tests/test_printer_cups_integration.py
Locally, the integration tests use system cupsd on :631 (user in lpadmin). Admin calls go through the Unix socket — HTTP to 127.0.0.1:631 hangs on addPrinter. Device URIs stay on 127.0.0.1 so cupsd can reach the mock printers.
CI builds and runs ghcr.io/agritheory/beam-cups:sha-<git-sha> as a workflow service published on host port 1631 (BEAM_CUPS_HOST / BEAM_CUPS_PORT). The container reaches mocks via the runner IP / host.docker.internal. Override with BEAM_CUPS_SAME_HOST=1|0 or BEAM_CUPS_MOCK_HOST=<ip>. Optional: CUPS_ADMIN_USER, CUPS_ADMIN_PASSWORD (defaults match cups/.env.example).
Pure logic tests run without CUPS. Integration tests use test_utils.printers mock servers (TCP raw + IPP) plus real pycups/CUPS queue creation.
A convenient Print Handling Unit button on relevant doctypes enables the user to print new Handling Unit labels directly from the ERPNext user interface.

Any configured network printers will display as options in the Select Printer Setting dialog.
