G1OS installation

Full procedure to flash G1OS (the Mainsail-based operating system) onto the Raspberry Pi 4 SD card inside the G1 printer. Required when reinstalling the OS or replacing the SD card.

This is not how you update

Reinstalling G1OS erases the serial, the configuration and the bed mesh. To update, see Updating the printer.

Download

Latest G1OS image: github.com/gingeradditive/G1OS/releases/latest

---

What flashing the card changes — and what it does not

Everything the printer knows about itself lives on the SD card, and the flash replaces all of it. Nothing else on the machine is touched.

	Erased by the flash
G1OS, Klipper, Moonraker, Mainsail	Yes — replaced by the versions in the image
Your serial number and machine configuration	Yes — the card comes back blank
Bed mesh, Z offset, SAVE_CONFIG values	Yes — you will recalibrate
G-code files you uploaded	Yes
Firmware on the Octopus, extruder_board and feeder board	No — see below

The card is not the firmware

The three control boards each hold their own firmware, in their own flash, and an SD card has no way to reach it. A newly flashed card talks to boards still running exactly what they ran yesterday.

That is what you want. The only board you flash is the Octopus, and only if, after the software update, the dashboard reports it out of date — see Flashing the Octopus.

---

When to do it

• First-time setup of a new machine
• OS is corrupted and the printer does not boot
• Replacing the SD card

Prerequisites

• Tools: hex screwdriver (to open electronics box), SD card reader/adapter
• Card: a 32 GB microSD, Class 10
• Files: the latest G1OS image — see step 2
• Software: Raspberry Pi Imager, the current version from raspberrypi.com/software
• Machine state: powered off

Nothing to set in Imager

The image already contains everything the printer needs: user pi, password raspberry, SSH switched on, and the name g1os (so the printer answers at g1os.local). You only choose the device, the file and the card.

---

Steps

1 — Remove the SD card from the printer

1. Turn off the printer
2. Open the electronics box: unscrew the two hex screws on the left side of the display
3. Locate the Raspberry Pi 4 behind the display
4. The SD card slot is behind the flat ribbon cable — gently remove the SD card

2 — Download the G1OS image

1. Open github.com/gingeradditive/G1OS/releases/latest — it always shows the newest release
2. Under Assets, download the file ending in .img.xz — for example 2026-10-22-G1OS-raspberry_pi-arm64-trixie-3.0.2.img.xz, about 1.5 GB. The .json and .sha256 files next to it are not the image

Do not unpack it. Raspberry Pi Imager reads .img.xz as it is, and unpacking only costs you disk space.

Each release also carries a .sha256 file next to the image. If the write fails or the machine will not boot afterwards, checking that first tells you whether you are chasing a bad download or a bad card.

3 — Flash the SD card with Raspberry Pi Imager

1. Insert the SD card into your computer and open Raspberry Pi Imager

2. Device — select Raspberry Pi 4, then NEXT

   

3. OS — scroll to the bottom of the list, click Use custom and pick the .img.xz you downloaded. It then shows as Local. Click NEXT

   

4. Storage — select your SD card, then NEXT. Check the size: it must be the 32 GB card, not another drive

   

5. Writing — Imager skips the Customisation step by itself. The summary shows Raspberry Pi 4, the G1OS file and your card. Click WRITE, then I UNDERSTAND, ERASE AND WRITE

   

6. Wait for Write complete, then take the card out

4 — Reinstall the SD card

1. Safely remove the SD card from your computer
2. Insert it back into the Raspberry Pi in the G1 printer
3. Reassemble and close the electronics box
4. Power on the printer

5 — Connect and configure G1OS

1. Connect the printer to your Wi-Fi from the Klipper menu on the display
2. From your PC, open a browser and go to g1os.local

   If the printer doesn’t connect via g1os.local, try restarting the router

---

Final verification

The G1OS Mainsail dashboard appears at http://g1os.local in your browser. The printer shows as connected and temperatures are visible.

What comes next

A flashed card is a blank printer. It boots, but it does not yet know which machine it is, and none of your calibration survived. Work straight down this list — each step needs the one above it.

1. Initialize the printer — give it your serial number, then press UPDATE G1 to download your machine’s own configuration. Until this is done the printer is running a generic config and printer.cfg does not describe your machine

   There is nothing to carry over from a card you just wrote — no old state, nothing to back up

2. Update the software components — press UPDATE ALL COMPONENTS in the Update Manager; flash the Octopus only if the dashboard then reports it out of date. The image ships with whatever was current when it was built

3. Re-check the boards are talking. STATUS in the console must show both mcu and extruder_board connected. The new printer.cfg picks up their USB addresses by itself; if one is missing, go to Klipper MCU communication lost — the cause is the USB cable or the serial: line, never the board’s firmware

4. Bed levelling — run BED_LEVEL hot and save. The old mesh is gone

5. Z offset and first layer — measure the first layer with a caliper and save

Steps 4 and 5 are the same calibrations as a brand-new machine, for the same reason: they were stored on the card you overwrote. Rotation Volume is not: it lives in the Ginger Slicer material profile and reaches the printer with every print. The rest of the commissioning checks are in the First boot checklist.

Notes

• The SD card slot is tight and partially hidden by the ribbon cable — be gentle to avoid bending the connector

Related notes

• Raspberry Pi and SD card
• Updating the printer
• Initialize the printer
• First boot checklist
• Mainsail dashboard basics