# Raspberry Pi Print Server: Local and Cloud Printing Guide

> Build a Raspberry Pi print server for local or cloud printing. Compare CUPS and an API-based setup, connect your printer, and send your first print job.

Published 2026-10-31 · https://printscaler.com/blog/raspberry-pi-print-server

![Raspberry Pi bridging a cloud application to a document printer and label printer on a warehouse workbench](https://printscaler.com/blog/images/raspberry-pi-print-server-6.jpg)

A **Raspberry Pi print server** lets you keep a printer connected without leaving a desktop computer running. For computers on the same network, CUPS can share a printer; for a cloud application, warehouse system, or remote office, a printing agent can connect the Pi to an HTTPS printing API. Choose based on where print jobs originate—not just which cable connects the printer.

This guide covers both architectures, then walks through using a Raspberry Pi with PrintScaler to receive PDF or RAW print jobs from your application.

## Choose a local or cloud Raspberry Pi print server

A print server bridges software and a physical printer. The important distinction is whether that software can already reach your local network.

### Use CUPS for local network printer sharing

CUPS is a printing system commonly used on Linux. It manages printer queues and can share them with other computers, typically through IPP.

This fits a small office where employees print from desktop applications and their computers can reach the Pi over the LAN or a VPN. A USB-only printer can remain attached to the Pi rather than to someone's laptop.

CUPS does not, by itself, give an internet-hosted application a managed cloud printing API. You would still need a secure network path or another bridge between that application and the local print server.

### Use a cloud agent for application-driven printing

For a SaaS application, order-processing service, or ERP hosted outside your building, the connection works differently:

```text
Your backend → HTTPS printing API → Pi agent → local printer
```

With PrintScaler, the agent on the Pi establishes an outbound WebSocket connection. Your backend submits a print job to PrintScaler, and the agent delivers it locally. You do not need to open inbound ports on the router.

This approach is useful when the Pi is an unattended bridge rather than a workstation where someone clicks Print.

| Requirement | Local CUPS sharing | PrintScaler agent on a Pi |
|---|---|---|
| Print from computers on the same LAN | A natural fit | Possible through an application integration |
| Submit jobs from a cloud application | Requires a reachable path or additional integration | HTTPS API submission |
| Share a USB printer | Yes, with compatible printer support | Yes, when the printer is available to the agent |
| Open inbound router ports | Not needed for LAN-only access | Not needed for the agent connection |
| Track application print jobs | Requires your own application integration | Job states, history, and webhooks |
| Queue jobs while the Pi is offline | Depends on the submitting system | Supported, with configurable expiration |
| Send printer-language commands | Requires a suitable queue or transport | RAW ZPL, EPL, and ESC/POS submission |

These approaches are not necessarily competing layers. On Linux, local printer configuration may still involve CUPS even when a cloud agent handles remote job delivery.

## What you need before setting up the Pi

Start with the hardware and one test document:

- A Raspberry Pi with a supported operating system for the agent package you download.
- A reliable power supply and storage device.
- Network access; wired Ethernet is often a sensible choice for a fixed installation.
- A USB or network printer compatible with your intended printing method.
- A PDF for document printing, or printer-language data for RAW printing.
- Administrator access to configure the Pi and its printers.

Check the current Raspberry Pi package instructions on the [PrintScaler download page](https://printscaler.com/download). Match the package to your installed operating system and architecture rather than assuming every Pi image uses the same installer.

### Check printer compatibility before planning the workflow

For PDF printing, verify that the Pi can use the printer through an appropriate local printing setup. A printer working on Windows does not automatically mean an equivalent Linux driver is available.

For RAW printing, verify the exact language supported by the printer. ZPL is for compatible label printers; ESC/POS is commonly used for receipt printers. Sending one language to a printer that expects another can produce nothing, errors, or literal command text.

If you already have a network printer, the Pi does not need a USB connection. It does, however, need a working local route to that printer.

## If you only need local sharing, start with CUPS

For a LAN-only print server, CUPS may be enough. On a Debian-based Raspberry Pi OS installation, a typical starting point is:

```bash
sudo apt update
sudo apt install cups
sudo usermod -aG lpadmin "$USER"
sudo systemctl enable --now cups
```

Log out and back in after changing group membership. You can then configure the printer using the local CUPS administration interface, normally available at `http://localhost:631` on the Pi.

Adding a printer and sharing it are separate steps. The printer driver, queue configuration, sharing settings, and firewall rules determine whether other devices can use it. Test locally first, then configure sharing for the intended network clients.

Do not forward the CUPS administration interface to the public internet to make a cloud application reach it. Use a deliberately secured network connection or an outbound cloud agent instead.

If your actual requirement is “print a packing slip when my hosted application creates an order,” continue with the cloud setup below.

## Set up a Raspberry Pi print server with PrintScaler

The goal is to prove each link separately: printer connectivity, agent connectivity, and API submission.

### 1. Connect and test the printer locally

Attach the USB printer to the Pi, or configure the network printer so the Pi can reach it. Install any required local driver or queue configuration for your printing method.

For PDFs, print a simple one-page document locally before introducing the cloud service. Check margins, orientation, and paper size.

For RAW printing, confirm the printer's command-language support and connection settings. A PDF test does not prove that the same printer accepts ZPL or ESC/POS.

This step separates local driver problems from API problems. If the Pi cannot reach the printer, a successful HTTP request will not fix that connection.

### 2. Install the agent and pair the Pi

Install the PrintScaler agent using the instructions for your Raspberry Pi package. In the PrintScaler dashboard, link the computer by entering its pairing code.

The agent runs in the background, starts automatically after reboots, updates itself, and reports printers and their status. Its outbound connection avoids the need for an inbound firewall exception or router port forward.

Outbound does not mean unrestricted: managed networks may still require permission for the agent's HTTPS and WebSocket traffic. If pairing fails, check DNS, internet connectivity, and your network's outbound policy.

### 3. Verify the printer in the dashboard

Open the linked computer in the dashboard and confirm that the intended printer appears. Use the printer's test-page button where appropriate, then record its printer ID.

Treat the printer ID as a configured destination in your application. For example, map a warehouse's packing-slip printer separately from its shipping-label printer. Do not assume a printer's display name uniquely identifies the correct physical device across every location.

### 4. Create an API key for your backend

Keep the API key in server-side configuration or a secret manager. Do not put it into a public browser bundle, mobile application, or source repository.

PrintScaler accepts a bearer token or the API key as an HTTP Basic username. The examples below use bearer authentication.

Your application should decide which printer a user or business event can target. Do not let an untrusted request choose arbitrary printer IDs without authorization checks.

### 5. Send your first PDF print job

Use a PDF URL that PrintScaler can retrieve. A URL requiring your browser's logged-in session will not work simply because it opens on your laptop.

```bash
export PRINTSCALER_API_KEY='psk_replace_with_your_key'
export PRINT_JOB_KEY='packing-slip-order-10482-v1'

curl --fail-with-body \
  --request POST \
  'https://api.printscaler.com/v1/printjobs' \
  --header "Authorization: Bearer $PRINTSCALER_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "X-Idempotency-Key: $PRINT_JOB_KEY" \
  --data '{
    "printerId": 123,
    "contentType": "pdf_uri",
    "content": "https://files.example.com/packing-slip-10482.pdf",
    "title": "Packing slip for order 10482"
  }'
```

Replace `123` and the example URL with your actual printer ID and document URL. Use a non-sensitive test document for the first run.

If a retrievable URL is unsuitable, `pdf_base64` lets you send the PDF bytes encoded as Base64 in `content`. Base64 is an encoding, not encryption or an access-control mechanism.

The [print jobs API reference](https://printscaler.com/docs#printjobs) covers submission details. Inspect the HTTP response and follow the job in the dashboard; API acceptance alone does not prove paper reached the output tray.

## Choose PDF or RAW for the printer's actual job

The Pi is a delivery bridge. It does not make a document format interchangeable with a printer command language.

### Use PDF for documents with page layouts

PDF is a practical choice for packing slips, invoices, reports, and other page-based documents.

PrintScaler supports PDF options including copies, duplex, paper size, tray, DPI, collate, color, fit to page, page ranges, rotation, and n-up. Read the printer's capabilities through the API before selecting paper sizes or trays; capabilities differ between printers.

Test the actual production document. A printer accepting A4 office PDFs does not establish that a narrow label layout will print at the intended physical size.

### Use RAW for compatible labels and receipts

For a ZPL-compatible label printer, send ZPL directly rather than wrapping the label in a PDF. For an ESC/POS receipt printer, RAW commands support receipt-specific operations such as cutting paper, opening a cash drawer, and printing QR codes. Sending ESC/POS raw is faster and sharper than PDF.

Here is a small ZPL submission from a Linux shell:

```bash
export LABEL_JOB_KEY='bin-label-test-001'

ZPL_BASE64="$(printf '%s' \
  '^XA^FO30,30^A0N,35,35^FDBin A-12^FS^XZ' \
  | base64 | tr -d '\n')"

curl --fail-with-body \
  --request POST \
  'https://api.printscaler.com/v1/printjobs' \
  --header "Authorization: Bearer $PRINTSCALER_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "X-Idempotency-Key: $LABEL_JOB_KEY" \
  --data "{
    \"printerId\": 123,
    \"contentType\": \"raw_base64\",
    \"content\": \"$ZPL_BASE64\",
    \"title\": \"Bin label test\"
  }"
```

Run this only against a ZPL-compatible destination, and adjust the layout for its media and resolution. For label-specific layout and delivery considerations, see the guide to [printing ZPL from cloud applications](https://printscaler.com/blog/print-zpl-from-cloud-zebra-printers).

## Make the print server reliable when unattended

A successful test is the beginning. Production needs rules for disconnects, retries, and stale work.

### Set expiration according to the document's usefulness

PrintScaler queues jobs while the computer is offline and prints them when it reconnects, subject to a configurable expiration time.

That behavior is useful for a temporarily disconnected packing station. It can be undesirable for a kitchen ticket that becomes irrelevant after service ends. Choose expiration based on the business event, not just how long you are willing to wait.

Also decide who handles expired work. An expired job may require a manual reprint, a reroute, or no action at all.

### Reuse the same idempotency key for retries

Suppose your application submits a job, then loses its connection before receiving the response. A blind retry could otherwise produce a duplicate.

Persist a unique `X-Idempotency-Key` with the logical print operation and reuse it when retrying that operation. Generate a new key for an intentional reprint. If the document changes, treat the revised print as a distinct operation rather than reusing a key with a different payload.

The example keys above are placeholders for individual test operations, not keys to reuse for every future order.

### Monitor job and connection events

PrintScaler exposes states including `new`, `sent_to_client`, `queued`, `in_progress`, `done`, `error`, `cancelled`, and `expired`, with full history.

Use [signed webhooks](https://printscaler.com/docs#webhooks) to update your application from job-state changes and computer connection events. Verify the HMAC-SHA256 signature and make your handler safe to process repeated deliveries, because webhook deliveries are retried.

Keep transport status separate from business confirmation. A completed print workflow is not the same as a worker confirming that the correct label was attached to the correct parcel.

### Test reboot and outage recovery

Before relying on the Pi, run a short acceptance test:

1. Print a PDF or RAW sample while everything is online.
2. Reboot the Pi and confirm the agent reconnects automatically.
3. Disconnect its network, submit a job, and restore connectivity before expiration.
4. Retry a submission with the same idempotency key and verify it does not print twice.
5. Test paper-out behavior and review the status information available for your printer.

Do not assume every printer reports every physical condition. Validate the signals your particular hardware exposes.

## Troubleshoot the failing layer, not the whole system

| Symptom | First checks |
|---|---|
| Pi does not appear connected | Power, internet access, pairing, agent service, outbound network policy |
| Printer is missing | USB connection, network reachability, local printer setup, agent-reported printers |
| Job waits while Pi is disconnected | Computer connectivity and job expiration |
| PDF is clipped or scaled incorrectly | Document dimensions, paper choice, scaling, local driver |
| RAW output shows command text | Printer language support and RAW delivery configuration |
| Duplicate output | Application retries, idempotency-key persistence, intentional reprint logic |

For bursty workloads, also respect the API rate limit of 10 requests per second with a burst of 30. Use an application queue to spread submissions rather than launching an unbounded batch.

## Costs and rollout planning

Budget for the Pi, power supply, storage, printer supplies, and the cloud service—not just the board.

PrintScaler pricing is per print request, not per page. The Free plan includes 100 prints per month and one computer, which can be a starting point for testing one Pi with its printers. Starter is $9 per month with 5,000 included prints and three computers. Check the [current plans and overage pricing](https://printscaler.com/pricing) before sizing a production deployment.

Estimate requests from actual workflow events. Printing a packing slip and then submitting a separate label is two requests. Include test prints and intentional reprints in your forecast.

## Put the Pi at the right boundary

Use CUPS when you need local printer sharing. Use a cloud-connected agent when your application needs a secure outbound bridge to a printer at a warehouse, store, or remote office.

Start with one printer and one document, prove reboot and retry behavior, and then expand. [Create a free PrintScaler account](https://printscaler.com/signup) to pair your Raspberry Pi and test the first API print job.

## Frequently asked questions

### Can a Raspberry Pi turn a USB printer into a network printer?

Yes, provided the Pi can use the printer through a compatible local printing setup. CUPS can share it with network clients, while a cloud printing agent can make it available to applications through a printing API.

### Do I need CUPS to use a Raspberry Pi with PrintScaler?

That depends on the printer, operating system, and printing method. Local Linux printer configuration may involve CUPS, especially for PDF printing; the PrintScaler agent handles the connection between the Pi and the cloud service. Verify the local printer setup before testing API delivery.

### Can I print remotely without opening ports on my router?

Yes. The PrintScaler agent uses an outbound WebSocket connection, so its cloud connection does not require inbound router port forwarding. Your network must still allow the required outbound traffic.

### What happens to print jobs when the Raspberry Pi is offline?

PrintScaler queues jobs while the computer is offline and delivers them when it reconnects, provided they have not expired. Set expiration according to the document's usefulness so stale tickets or labels do not print unexpectedly.

### Can a Raspberry Pi print server print shipping labels and receipts?

Yes, with compatible printers and the correct document format. PrintScaler accepts PDFs and RAW data, including ZPL or EPL for compatible label printers and ESC/POS for compatible receipt printers.

### Does each printer connected to the Pi count as a separate computer?

No. A Pi running the agent is one computer, and the Free plan includes all printers on that one computer. Print usage is billed per print request rather than per page.