GuidesKlipper Firmware

How to Install MainsailOS on Raspberry Pi

In this article, I will show you how to install MainsailOS on Raspberry Pi and upgrade it to the latest version. Mainsail V1.0.0 just launched and I think it’s a good opportunity to use it now as a main interface for Klipper.

What is MainsailOS?

MainsailOS is a Raspbian image customized to be as lightweight as possible, while also having most of the required services already installed. This means that you won’t have to install Klipper or other services manually because they come already installed and configured.

As the name implies, Mainsail is the default web interface used to control Klipper. It’s quite similar to the RepRapFirmware web interface, but with functionality added specifically for Klipper.

Mainsail OS Interface | How to Install MainsailOS on Raspberry Pi

All you have to do after installing MainsailOS is to load the correct config file for your 3D printer, then start the calibrations.


  1. Raspberry Pi – It works on any Pi, even on a Raspberry Pi Zero.
  2. MicroSD Card – High Speed MicroSD Card is recommended
  3. Good power supply for the Pi – Any adapter works if it’s capable of delivering at least 2.5 A of power

Install MainsailOS on Raspberry Pi

Flash Mainsail OS on the SD Card

Before we install MainsailOS we need to first download the latest release from Github. At the time of writing this guide, MainsailOS reached V0.2.0.

Download the MainsailOS image then unzip the archive.

Download MainsailOS | How to Install MainsailOS on Raspberry Pi

Download and install Win32 Disk Imager.

Download Win32 Disk Imager

Open Win32 Disk Imager, load the .img file unzipped in previous step and select your SD card drive letter. Click on Write to begin installing MainsailOS on the SD card. This process will take a few minutes, depending on the speed of your SD card.

Write MainsailOS on SD Card | How to Install MainsailOS on Raspberry Pi

After the Mainsail OS image has been flashed, we need to edit the Wi-Fi credentials to auto-connect. You can skip this step if you don’t use a wireless setup.

Set your Wi-Fi credentials

In order to auto-connect the Raspberry Pi to Wi-Fi, we need to edit a file on the SD Card and insert the Wi-Fi credentials.

In your explorer window, navigate to the boot partition, and open the mainsailos-wpa-supplicant.txt file in Notepad / Notepad++ (don’t use other file editors).

WPA Supplicant for Mainsail OS | How to Install MainsailOS on Raspberry Pi

In this file, we need to uncomment line 27,28,29 and 30 then enter the Wi-Fi credentials. To do that, remove the “ # ” character in the front of the line.
Next, enter your Wi-Fi name and password.

In this example, my Wi-Fi is named “MyHomeNetwork” and the password is “SuperS3cretP@ssword

This is how the file looks before entering the Wi-Fi credentials:

image 1 | How to Install MainsailOS on Raspberry Pi

This is how the file should look after you entered your Wi-Fi credentials:

image | How to Install MainsailOS on Raspberry Pi

Now save the file, and remove the SD Card. Insert it into your Raspberry Pi then start it up. In a few minutes, MainsailOS will boot up and you will be able to access the web interface. If this hyperlink doesn’t open the Mainsail OS web interface for you, find the IP address of your Raspberry Pi.

Find the IP of your MainsailOS Web Interface

In order to connect to your MainsailOS web interface, you first need to find the IP address your Raspberry Pi received from the DHCP server.

Press Windows Key + R at the same time to open Run. Type cmd.exe then press Enter to open Command Prompt.

Open Command Prompt

In the Command Prompt window, type ping mainsailos.local -4 and press enter. This will return the IP of your Raspberry Pi.

Ping Raspberry Pi to find IP of Mainsail OS | How to Install MainsailOS on Raspberry Pi
How to Install MainsailOS on Raspberry Pi 1

Install KIAUH

Next step would be to install KIAUH which stands for Klipper Installation And Update Helper. It’s an excellent tool which will make the whole Klipper installation process much easier.

To install KIAUH, we fist need to connect via SSH to the Raspberry Pi.

Connect via SSH

Download Putty , enter the IP of your Raspberry Pi then click Open

Connect via SSH to Raspberry Pi | How to Install MainsailOS on Raspberry Pi

The servers’ SSH fingerprint prompt will show up. Click on Yes.

image 2 | How to Install MainsailOS on Raspberry Pi

In the Login prompt, you need to enter the credentials for MainsailOS. The default user is pi and the password is raspberry. Please note that the password will not be shown when typing.

image 3 | How to Install MainsailOS on Raspberry Pi

Now you are in the SSH console of your MainsailOS install.

image 4 | How to Install MainsailOS on Raspberry Pi

Install KIAUH

Clone the git repository for KIAUH with the following command

git clone

After the cloning process is complete, navigate to the kiauh folder

cd kiauh

Set the proper permissions for all the files in the kiauh scripts folder

chmod +x scripts/*

Finally, run the installation script


The KIAUH GUI will show up, where you can choose to install different packages and services. You can use your keyboard to enter your selection.

image 5 | How to Install MainsailOS on Raspberry Pi

Update MainsailOS Packages

If you followed the steps correctly, then you can now open the MainsailOS web interface, and you will be greeted by this screen.

Mainsail OS Homepage | How to Install MainsailOS on Raspberry Pi

I recommend starting to update all the packages to make sure you are running the latest and greatest for Klipper. This can be performed from the Settings tab.

Update services in MainsailOS | How to Install MainsailOS on Raspberry Pi

Upgrading the packages is as easy as clicking any of the update buttons when they are available, then waiting for the process to complete.

Wrapping up

With MainsailOS now installed and updated, you can go ahead and upload your configuration file then start the calibration process. You can find configuration files for a few of my printers in the Klipper section of the website.

If you encounter any issues, leave a comment, or join the 3DPrintBeginner Discord server where you can get assistance.

Liked it?
Take a second to support 3DPrintBeginner on Patreon!

Notify of
Inline Feedbacks
View all comments
6 months ago

Would you please update this tutorial? There are multiple cases so far that peopel have not been able to get klipper installed because they followed this and its outdated…

For on Kiuah is far from the easiest option right now. Just using mainsail OS or FluiddPi can be installed in 15 minutes and they have updates inside of them. You dont need KIUAH at all anymore.

Albie Castro
Albie Castro
7 months ago

I had problems with Raspberry Pi 4 8 gig not reading the wifi. I did what was suggested in your article.
The only way I got it to work is to add this line to the end of the Wifi section:


It now looks like this:
## WPA.WPA2 secured

Just in case someone has the same problem.
Thanks for the information it made installing the OS easy, and it is very informative.

Yannick CROQ
Yannick CROQ
8 months ago

Hi !
could you create the configuration files for the flsun Q5 under Klipper ?