Linux & WSL printing

On Linux (including WSL), winprint provides the wp terminal UI and headless wp print — not the graphical app. Printing uses the system’s CUPS setup: --printer is a CUPS queue name. There is no Windows-style printer picker in the headless path.

Install wp first (see Install). This page is about getting printers (or a PDF file) working so wp print has somewhere useful to send output.

Prefer --pdf when you only need a file

wp print mermaid.md --pdf mermaid.pdf --sheet "Proportional 1-Up"

No printer queue, no driver, no dialog. Works the same on bare-metal Linux and WSL. Use this when you want a PDF on disk rather than paper (or a virtual “print to PDF” queue).

--pdf and --printer cannot be combined.

List printers

lpstat -p          # printers and state
lpstat -a          # queues accepting jobs (name is the first word)
lpstat -d          # system default destination
lpstat -t          # full status dump
lpstat -o          # outstanding jobs

The name for wp print … --printer NAME is that first word, e.g. PDF or Brother-HL-L3230CDW.

Set a default (optional):

lpoptions -d Brother-HL-L3230CDW   # per-user
# sudo lpadmin -d Brother-HL-L3230CDW   # system-wide

With no --pdf and no --printer, wp print uses the system default destination. If nothing is configured, it errors and tells you to add a queue, pass --printer, or use --pdf.

Install CUPS

# Debian / Ubuntu / WSL
sudo apt update
sudo apt install -y cups cups-client cups-bsd
sudo service cups start   # or: sudo systemctl start cups

lpstat -r                 # expect: scheduler is running

# Fedora / RHEL
sudo dnf install -y cups
sudo systemctl enable --now cups

If you want a CUPS “print to PDF” queue (instead of --pdf):

# Debian / Ubuntu
sudo apt install -y printer-driver-cups-pdf
# Fedora
# sudo dnf install -y cups-pdf

lpstat -p                 # usually "PDF" (Debian/Ubuntu) or "Cups-PDF" (Fedora)

wp print mermaid.md --printer PDF --sheet "Proportional 1-Up"
# Output directory is ~/PDF/ by default (see Out in /etc/cups/cups-pdf.conf)
ls ~/PDF/

For a simple file on disk with no queue, prefer wp print … --pdf out.pdf.

Install a network printer (IPP)

Most modern LAN printers (Brother, HP, Epson, …) speak IPP. CUPS can use the generic everywhere driver — you usually do not need a Windows or vendor driver inside Linux.

Example: Brother HL-L3230CDW at 192.168.1.104:

ping -c 2 192.168.1.104

sudo lpadmin -p Brother-HL-L3230CDW -E \
  -m everywhere \
  -v ipp://192.168.1.104/ipp/print \
  -D "Brother HL-L3230CDW" \
  -L "LAN"

lpoptions -d Brother-HL-L3230CDW    # optional default
lpstat -p -a -d

Test:

echo "hello from CUPS" | lpr -P Brother-HL-L3230CDW
wp print README.md --printer Brother-HL-L3230CDW --sheet "Proportional 1-Up"

If that URI fails

Firmware varies. Remove and retry:

sudo lpadmin -x Brother-HL-L3230CDW

sudo lpadmin -p Brother-HL-L3230CDW -E -m everywhere \
  -v ipp://192.168.1.104/ipp/port1
# or:
#   -v http://192.168.1.104:631/ipp/print

Optional discovery:

sudo apt install -y avahi-utils cups-ipp-utils
ippfind
# printer web UI is often http://192.168.1.104/

Install vendor Linux packages only if the generic driver misprints (margins, duplex, color). Prefer IPP first.

WSL notes

WSL2 is a separate Linux environment. Windows and WSL do not share printer lists.

Expectation Reality
lpstat shows “Microsoft Print to PDF” No — that is Windows-only
Printers added in Windows Settings appear in WSL No — add a CUPS queue in Linux
wp print file with no queues configured Errors — set up CUPS or use --pdf

Recommended on WSL

  1. wp print … --pdf out.pdf, then open on Windows (explorer.exe out.pdf) if you only need a file.
  2. Or add a network IPP queue (above) so --printer reaches the device on your LAN.

Windows-shared printers from WSL (optional): share the printer on Windows, then add an SMB queue in CUPS (smb://<windows-host>/ShareName). The Windows host from WSL2 is often the nameserver in /etc/resolv.conf. Prefer talking to the printer’s own LAN IP when it has one.

WSL networking: the distro must reach 192.168.x.x printers. If ping fails, fix Windows/WSL networking (firewall, mirrored mode, VPN) before debugging CUPS.

Quick recipes

# File only — no printer required
wp print demo.md --pdf ./demo.pdf --sheet "Proportional 1-Up"

# Count sheets without printing
wp print demo.md --what-if --sheet "Proportional 1-Up"

# cups-pdf virtual queue
wp print demo.md --printer PDF

# Physical network printer (queue name from lpstat -a)
wp print demo.md --printer Brother-HL-L3230CDW --sheet "Proportional 1-Up"

Troubleshooting

Symptom What to check
No print destination is configured lpstat -a empty → install cups-pdf or an IPP queue, or use --pdf
No default printer is set Queues exist but none is default → wp … --printer NAME or lpoptions -d NAME
Unknown printer '…' Typo or wrong name → lpstat -a
Unable to launch 'lpr' Install cups-client / cups-bsd
lpstat: scheduler is not running sudo service cups start
Job accepted, nothing prints lpstat -o, printer power/network, wrong IPP URI; try lpr -P NAME /path/to.pdf alone
WSL can’t ping the printer Windows/WSL network path

More detail: wp --debug. Logs on Linux live next to the wp executable (see Support).

See also