Mainsail vs Fluidd: Which Interface Should You Run?

For the Mainsail vs Fluidd which interface question, pick Mainsail if you are flashing a fresh host, because MainsailOS is the maintained one-image install, or if you watch several printers at once. Pick Fluidd if you install through KIAUH and prefer its dashboard. Print quality is identical: both drive the same Klipper through Moonraker.

That last point is why the choice costs less than it looks. Neither interface plans motion or stores your tuning. Rotation distance, pressure advance and input shaper values live in printer.cfg on the host, and the web UI is a static front end talking to Moonraker’s API. Switching is a front-end reinstall and a one-line include change, not a re-tune. Both projects are GPL-3.0 and both ship often: Mainsail v2.19.0 landed on 27 August 2026 and Fluidd 1.37.6 on 23 September 2026.

What actually differs between Mainsail and Fluidd?

Less than forum threads suggest. The real differences are the install path (a prebuilt MainsailOS image versus KIAUH), how each models several printers, and a few conventions around macros and cameras. Features that once separated them, including macro prompt dialogs, Spoolman and Happy Hare or AFC multi-material panels, now exist in both.

Table data is from the Mainsail docs, Fluidd’s getting-started page and both release pages.

Which is easier to install on a new Klipper host?

Mainsail, by one step. MainsailOS is a prebuilt image bundling Mainsail, Moonraker, Klipper and their dependencies: flash a card, boot, open a browser. Fluidd’s docs recommend KIAUH and say FluiddPi is not under active maintenance, so the Fluidd route is a Lite OS image first, then a KIAUH session.

Neither route is hard. KIAUH lists Klipper, Moonraker, Mainsail, Fluidd and KlipperScreen as core components, and it is also how most people add or remove a front end later. Mainsail’s docs list Raspberry Pi and several Orange Pi boards as MainsailOS targets. If you are still choosing the host board, the tradeoffs are in Klipper hardware requirements.

One host-side setting matters more than the UI on small boards. Cancelling individual objects needs [exclude_object] in printer.cfg plus Moonraker’s object preprocessing, and Fluidd’s example moonraker.conf says to leave that preprocessing off on a low-powered device such as a Pi Zero.

How do Mainsail and Fluidd handle several printers?

Both connect to multiple Moonraker instances from one page, but they model the job differently. Mainsail adds printers under Interface Settings and gives you a print farm overview alongside the switcher. Fluidd switches printers inside a single tab, fully reloading settings and state, and keeps a separate auth token for each machine.

Each entry in Mainsail’s printer settings takes a hostname or IP, the Moonraker port (default 7125) and a path, which matters when Moonraker sits behind a reverse proxy under something like /printer1. Where that list lives is set by instancesDB in config.json. The default moonraker mode suits small setups but is flagged as problematic under Docker, because the primary printer must be reachable before Mainsail can load the list. The documented choice for farms and Docker is json mode, which fixes the list in the file:

{
  "instancesDB": "json",
  "instances": [
    { "name": "corexy-left", "hostname": "192.168.1.101", "port": 7125 },
    { "name": "corexy-right", "hostname": "192.168.1.102", "port": 7125 },
    { "name": "bedslinger", "hostname": "192.168.1.103", "port": 7125 }
  ]
}

Fluidd’s multi-printer page describes a different shape. Connection details are saved locally, each printer gets a bookmarkable ?printer= URL, display names are stored in that printer’s Moonraker database, and each machine can have its own user accounts and login requirement. Its Docker image is pitched at exactly this case: one Fluidd instance managing several printers.

The practical split: if you want three or more machines on one glanceable screen, Mainsail’s farm overview in json mode fits better. If you have two printers with different login policies, Fluidd’s per-printer auth is cleaner.

Whichever you run, keep it off the open internet. Mainsail’s remote access FAQ asks users not to forward Mainsail or Moonraker ports and recommends a WireGuard, OpenVPN or PiVPN tunnel, or a service such as Tailscale. That applies to Fluidd too: the exposed surface is Moonraker either way.

Macros, prompts and the bundled config

This is where the two are closest. Each ships a Klipper include that supplies [virtual_sdcard], [display_status] and [pause_resume] plus PAUSE, RESUME and CANCEL_PRINT macros with parking and retraction. Fluidd’s configuration page warns at startup when those sections or a CANCEL_PRINT macro are missing, and the fluidd-config README credits its client.cfg to the Mainsail Crew, prepared jointly by both teams’ maintainers.

Both are customized the same way: never edit the include; copy _CLIENT_VARIABLE below it and override. Mainsail’s defaults are a 1.0 mm retract at 35 mm/s on PAUSE, the same unretract on RESUME, a 5.0 mm retract on cancel and a 2.0 mm Z lift when parking. A bowden machine that oozes during long pauses may want more retract.

[include mainsail.cfg]

[gcode_macro _CLIENT_VARIABLE]
variable_use_custom_pos : True
variable_custom_park_x  : 150.0
variable_custom_park_y  : 10.0
variable_cancel_retract : 5.0
gcode:

Fluidd’s README shows the same macro name and park-position variables, so the block usually moves across with only the include line changed. Diff the two _CLIENT_VARIABLE macros before relying on that.

Both now render action:prompt dialogs: Mainsail since v2.9.0 and Fluidd since v1.27.0, which added Prompt Dialog support. Macros send them with RESPOND TYPE=command, so [respond] must be in printer.cfg. A filament-change confirmation:

[respond]

[gcode_macro FILAMENT_CHECK]
gcode:
    RESPOND TYPE=command MSG="action:prompt_begin Filament change"
    RESPOND TYPE=command MSG="action:prompt_text New filament loaded and purged?"
    RESPOND TYPE=command MSG="action:prompt_footer_button Resume|_PROMPT_RESUME|primary"
    RESPOND TYPE=command MSG="action:prompt_footer_button Cancel|_PROMPT_CANCEL|error"
    RESPOND TYPE=command MSG="action:prompt_show"

[gcode_macro _PROMPT_RESUME]
gcode:
    RESPOND TYPE=command MSG="action:prompt_end"
    RESUME

[gcode_macro _PROMPT_CANCEL]
gcode:
    RESPOND TYPE=command MSG="action:prompt_end"
    CANCEL_PRINT

The underscore prefix matters in Fluidd: its macro page hides any macro starting with _ from the panel and lets you sort the rest into colored categories, useful once an MMU config adds dozens of macros.

Cameras and timelapse

Neither interface captures video. Each displays a stream from a separate service, so latency and frame rate depend on the streamer and the camera, not the UI. Fluidd’s camera docs list the stream types it accepts: MJPEG, adaptive MJPEG, UV4L-MJPEG, HLS, WebRTC through camera-streamer, go2rtc or MediaMTX, an IP camera, or an HTTP page. Mainsail hands streamer setup to Crowsnest; v2.17.0 added an iframe webcam option and v2.18.1 fixed go2rtc stream URLs.

If the feed lags, Fluidd’s FAQ suggests a USB 3.0 port or a lower frame rate and resolution, which holds on either interface. Timelapse comes from the moonraker-timelapse component, which Mainsail’s feature list names directly.

Does the interface change print quality?

No. Both send commands to the same Moonraker, which hands G-code to the same Klipper host; step timing is computed on the host and executed by the MCU regardless of which browser tab is open. Ringing, corner bulge and seam quality come from printer.cfg values such as pressure_advance, square_corner_velocity and the [input_shaper] frequencies.

What the interface changes is how pleasant tuning feels. Both give you a console for tuning-tower and resonance commands, a bed mesh view and an in-browser config editor, so the procedures in the pressure advance calibration guide and the ADXL345 input shaper setup run identically in either. The host and MCU split behind that is covered in how Klipper works.

Who should run which?

Run Mainsail if you are building a new host and want one image to flash, you run three or more printers and want them on one overview, or you deploy in Docker with a fixed printer list in config.json.

Run Fluidd if you already manage the host with KIAUH, you want a long macro list sorted into colored categories, you need separate logins per printer, or you want a Docker image with an unprivileged variant and a health check.

Try both if you are unsure. Serving two static front ends on different ports costs little, and a week of real prints settles it faster than a table. Each updates through Moonraker’s update manager with a type: web block, as Mainsail and Fluidd document:

[update_manager mainsail]
type: web
channel: stable
repo: mainsail-crew/mainsail
path: ~/mainsail

[update_manager fluidd]
type: web
repo: fluidd-core/fluidd
path: ~/fluidd

FAQ

can you run mainsail and fluidd at the same time

Yes. Both are static web front ends that open their own WebSocket connection to Moonraker, so one host can serve Mainsail and Fluidd on different ports and both will show the same printer state. Keep only one bundled include in printer.cfg, since mainsail.cfg and fluidd.cfg define the same PAUSE, RESUME and CANCEL_PRINT macros.

do mainsail and fluidd need moonraker

Yes, both do. Neither talks to Klipper directly; each is a browser front end for Moonraker’s API, and both projects’ setup docs list Klipper, Moonraker and the interface as the three required pieces. MainsailOS and KIAUH install all three together, so Moonraker rarely needs hand edits until you add CORS entries or a second printer.

is fluidd lighter than mainsail

Not in any way that shows up on the host. Both projects describe themselves as lightweight and responsive, and either one is a folder of static files behind a web server, so Klipper host load barely changes. Rendering happens in your browser, so a sluggish G-code viewer or webcam tile points at the viewing device or the streamer.

how do i switch from fluidd to mainsail

Install Mainsail with KIAUH, then swap the fluidd.cfg include for mainsail.cfg in printer.cfg, carry your _CLIENT_VARIABLE overrides across, and add an update_manager mainsail block to moonraker.conf. Run FIRMWARE_RESTART afterwards. Your printer.cfg, macros, print history and G-code files stay on the host, so nothing about the printer needs re-tuning.