Headless Linux vision server install: skip the GUI, keep the X libs

The vendor's Linux installer pulls in X client libraries and GUI tools, and on an unattended vision box every package looks like waste. The question reaches our bench regularly: can the install be stripped to a bare runtime? It can — but not by forcing packages out of the database. Forcing the X libraries away costs vendor support and saves kilobytes, while installing on a desktop-free server and deleting the viewer binaries afterward saves the real space and changes nothing about acquisition. This guide gives the decision, a numbered procedure, the network and bandwidth numbers that size the box, and the service setup that runs GenICam acquisition from boot with no monitor attached.

Can you skip the X libraries a vision SDK installs on Linux?

No — leave them installed, because the SDK vendor supports only the install exactly as it ships, the GUI tools link libxinerama0 and its siblings, and the whole set of X client libraries costs kilobytes to a few megabytes of disk.

libxinerama0 is a client library for an X display extension that reports monitor geometry to GUI toolkits. A viewer window uses it; an acquisition process that never opens a window does not. The install script pulls it in because the shipped GUI tools link against it, not because image transfer needs it. That distinction is what makes deleting the tools safe and deleting the libraries pointless.

Forcing the libraries out breaks two things. The package database is left inconsistent, so the next apt run tries to repair what you removed. And if any SDK binary links one of them, it fails at load with a shared-library error naming the missing file — the failure mode described in Linux vision shared library errors: diagnose missing dependencies.

SDK vendors test what their installer produces and answer support questions against that system, so a hand-pruned install sits outside support. The X client libraries are the small change. The megabytes you want back live in two places: the OS desktop you never install, and the viewer binaries you delete afterward — the next two sections.

How do you install the runtime on a server with no desktop?

Install the complete SDK on Ubuntu Server, a system that never had a desktop environment, then delete the viewer binaries afterward, because nothing in the GenICam or GigE Vision acquisition path opens a window and the runtime runs from boot with no display.

Ubuntu Server installs without any desktop environment, so the box boots to a shell with no display server running. The SDK installs completely anyway — installer scripts do not check for a GUI — and the parts you do not want are removable afterward.

1. Install Ubuntu Server (the current long-term-support release) with the SSH server option enabled and no desktop task selected.
2. Leave the camera port unconfigured for now; the network section below has the addresses and buffers.
3. Run the SDK installer from the SSH session and accept its full dependency list, X libraries included. If the SDK ships a runtime package separate from its development and GUI packages, install the runtime package and stop; where it ships one indivisible installer, install it whole.
4. Prove acquisition works display-free with your own grab test: open the camera, take 100 frames at its rated frame rate, and print a per-frame checksum. The checksum must change when you wave a hand in front of the lens and hold steady with a lens cap on.
5. Delete the viewer binaries as the next section describes, then run the identical grab test. The same 100 frames and the same checksum behavior prove you removed nothing acquisition needs.
6. Reboot with no monitor connected and run the grab test once more. That final pass is the whole proof.

Library layout on one machine has its own traps — mixed bitness, two copies of one library — and installing 32-bit and 64-bit vision libraries side by side on one PC covers them. The same rule holds here: one installer, one record, no hand-edits.

Which files can you delete after the install, and which must stay?

Delete only the interactive viewer binaries in the SDK's bin directory — its GenICam browser and license-display GUI — and the desktop shortcuts that point at them, while the runtime libraries, GenTL producer, filter driver and licensing service all stay.

The viewer applications are the bulky part of the optional install. On typical vision SDKs their binaries, help files and translations add up to tens of megabytes, while the X client libraries behind them are the small change. Delete the binaries, leave the shared libraries in place, and the package database stays consistent. A license display window can go; the background license service it talks to stays.

A viewer left on the box is not just dead weight: it can open the camera and hold it, which starves your service. That contention is exactly what camera feature browser freezes during image acquisition describes, and one client per camera is the rule whether the box has a display or not.

Treat post-install deletion as repeatable: keep the original installer archive on your file server, and a clean reinstall restores everything you removed in one step.

What must the network do before a headless box sees its first camera?

Give the camera's NIC an address in 169.254.0.0/16 or set a static one there: GigE Vision cameras without a persistent address come up link-local in that range, and the management NIC stays separate for SSH and updates.

A camera port and a management port do different jobs. The camera port carries image UDP only; the management port carries SSH, updates and logs. Keeping them physically separate means a full-rate camera stream never competes with your terminal session. The subnet-and-link checklist in 3D camera not pingable on a Linux controller: fix subnet and link applies to any GigE Vision camera, 3D or not.

Then tune the pipe. Enable jumbo frames (MTU 9000) on the camera port and in the camera. Raise the kernel's UDP receive buffer — stock defaults sit near a few hundred kilobytes, while streaming vendors commonly set the rmem ceiling between 16 and 64 MB. Let UDP port 3956 through the firewall, because GigE Vision control traffic uses it. When a maintenance session and the acquisition service both want the same camera, the ownership pattern in connect a camera only when subscribed to free the GigE link settles who gets it.

How much image bandwidth must the box sustain without dropping frames?

Compute frame size times frame rate per camera and keep each GigE camera under about 118 MB/s — the practical payload of a 1 Gb/s link with jumbo frames — and put anything faster on USB3 or a faster interface, since a 12 MP camera at 9 fps already takes 108 MB/s.

Worked example, 12 MP class, 8-bit output. One frame is 4000 × 3000 pixels × 1 byte = 12 MB. Thirty of them per second is 30 × 12 MB = 360 MB/s, about 2.9 Gb/s — impossible on a 1 Gb/s link and comfortably inside USB3, which moves roughly 400 MB/s of real payload against 500 MB/s raw. The LS-CMR-0166 is exactly this camera: 12 MP, 4000 × 3000 pixels, 30 fps over USB3.

The same frame on GigE: 9 fps × 12 MB = 108 MB/s, about 92% of the practical 118 MB/s. The LS-CMR-0053 prints 12 MP at 9 fps over GigE, and the arithmetic says that rate is the link's honest ceiling. Two such cameras cannot share one port — 216 MB/s against 118 MB/s of capacity — so each needs its own.

Size the box on those two numbers: per-camera MB/s and port count. Shortlist by interface — GigE or USB3 — in the area scan cameras category; its camera finder does the filtering.

These are the two cameras from the math.

Which vision controller suits an unattended, display-free install?

The MV-VC5525-256G70-NN provides five-plus LAN ports, PoE camera ports, 32 GB of memory and 8 built-in light channels, and the MV-VC2140-128G40-1T brings 3-4 LAN ports with 8 GB of memory and an Intel N97.

Size the box by ports: one per GigE camera plus one for management. Four cameras plus management is five ports, so the five-plus-port class covers a four-camera headless box outright, and the 3-4-port class handles the smaller install with a port to spare.

Memory sizing, worked: after a server OS and an SDK runtime take roughly 2 GB (typical), an 8 GB controller keeps (8 − 2) × 1000 ÷ 12 ≈ 500 twelve-megabyte frames of backlog — about 55 seconds of buffer at a 9 fps camera. The 32 GB class raises that roughly fivefold.

The built-in light channels matter headless too: they drive and strobe the illumination directly from the controller, so no desktop tool sits in the trigger path. Pair them with sources from the lights finder.

For the multi-camera headless box, this is the controller the port math points at.

For one or two GigE cameras, the entry box carries the identical procedure.

Browse the full vision controllers range to match ports, memory and light channels to your camera list.

How do you run, watch and update acquisition with no display attached?

Run the acquisition program as a systemd service that starts after the network comes online, restarts on failure and logs to the journal, and deploy, watch and restart it entirely over SSH.

An illustrative unit of our own — the names are ours, not the SDK vendor's:

# illustrative systemd unit; paths and flags are ours, not the vendor's
[Unit]
After=network-online.target

[Service]
ExecStart=/usr/local/bin/acquire --camera main --continuous
Restart=on-failure

[Install]
WantedBy=multi-user.target

The journal keeps that service's output, and SSH reads it. For the images themselves, publish rather than display: write frames to a network share or restream them, as restream an RTSP stream for display in an HMI browser shows, and keep every screen on a client machine. For multi-camera services, start each camera session from a known state — the discipline in 3D camera test flaky on leftover settings: start from a known state maps onto a systemd template unit directly.

Updates stay unattended as well: security patches on a schedule, kernel updates in a maintenance window with a planned reboot, image logs under rotation so the system SSD never fills. Ansible, Rundeck and plain cron cover this pattern, and the Linux server automation tools: Ansible, Rundeck and cron guide lays the three out.

When is headless the wrong choice?

During algorithm development — tuning blob tools, matching parameters or exposure behavior interactively against a live camera wants an image on screen in front of you, so develop on a workstation with a display and deploy the identical code to the headless box.

Commissioning is the second exception. Timing a multi-camera trigger chain or aiming a strobe is faster with a screen on the box; plug one in for the afternoon and remove it afterward. Nothing in the final configuration should depend on that monitor having existed. If a step genuinely needs the GUI tools, run them once from a workstation against a development camera, then keep the production box headless.

Everything after commissioning — the steady-state months — belongs to the headless install: fewer processes, fewer updates, and no idle viewer that can grab the camera out from under your service.

Send the camera list — model, resolution, frame rate — to /quote/, and we will match port count, memory and light channels to the bandwidth math above. More install-and-integration guides sit on the systems topic page.