• Čeština
  • Español
  • Italiano
  • Deutsch
  • Polski
  • Français
  • 日本語

Octoprint - Configuration and install

Last updated 7 months ago
This article is also available in following languages: 

This article covers how to configure your own image for any Raspberry Pi (RPi) from scratch. Following this article, you will have connected a base installation of Octoprint which you can expand upon. It will also include how to configure the Raspberry Pi Zero to be connected by its GPIO pins. However, the Raspberry Pi Zero is not powerful enough to utilize advanced Octoprint features and plugins, like video streaming, and is officially not recommended by the Octoprint project. 

We used to offer PrusaPrint, a custom build for the Raspberry Pi Zero. This is currently outdated and unmaintained. However, the guide soldering and connecting the RasPi is still valid for all MK3/MK3S/MK3S+ printers and can also be used not only for Octoprint, but also for the Prusa custom remote printing solutions, PrusaLink and PrusaConnect.
This article will cover:

Required parts

  • A Raspberry Pi A, A+, B, B+, 2B, 3A+, 3B, 3B+, 4B 1/2/4GB, or Zero W/2 + PSU.
  • WiFi dongle if your RasPi does not have built-in WiFi.
  • USB Cable:
    • Original Prusa i3: USB type-A cable.
    • Original Prusa MINI: Micro USB cable.
  • An SD or microSD card for your RasPi of at least 8GB.
  • Computer with a working SSH client, like PuTTY. Mac/osX and Linux have SSH integrated into their Terminal.
  • A (micro)SD card-reader to flash your SD-card.
  • WiFi network.
If you are installing the RPi Zero over GPIO, you must have soldered the header pins before you proceed!

Flashing the Octoprint image

Since the Raspberry Pi Foundation released their "Raspberry Pi Imager", it is no longer necessary to edit config files after flashing. All can be configured in the imager, within its Advanced options menu. Raspberry Pi Imager even allows you to download images through it. Let's go through it.

  1. Download and install the Raspberry Pi Imager for your computer. This is found here.

  1. Click the 'CHOOSE OS' button and navigate to ‘Other specific purpose OS’ -> ‘OctoPi’ -> ‘stable’ version.
  1. Enter the Advanced Options by pressing Shift + Ctrl + X. Enable SSH to set a hostname (name of the RPi on the network) and main password right away, as well as your WiFi network and password to connect to the Raspberry Pi later.

  1.  After this, select your SD card under 'CHOOSE STORAGE', before clicking 'WRITE' to start the flashing process.
You can edit the WiFi password and network later from the file "octopi-wpa-supplicant.txt" located on the SD card or over SSH explained later in this article.

Connecting the RasPI

Insert the (micro)SD card into your RPi and connect it to the printer by USB. After this, power your RPi. The Raspberry Pi Zero W will be connected to the printer using its GPIO pins, not USB. We recommend doing this before proceeding. However, for these configurations, you can power it using a 5V phone charger and connect it later.

If you use RPi Zero over GPIO, RPi port should be 'On'. However, it also requires further configuration outlined later in this article.

When using USB to connect to the printer, deactivate the RPi port (LCD menu -> Settings -> RPi Port and set it to "Off").

All Raspberry Pis can be connected by USB. The exception is the RPi Zero, which can also be connected by its GPIO pins to the MK3S' Einsy Rambo. If you intend to use the RPi Zero, you can still follow this guide to the end, where GPIO configuration is covered. Connecting the RPi Zero by USB or any other RPi by GPIO is possible, but has few if any, benefits.
MK3s/MK2.5S USB Type-B USB portMINI Micro USB port

Finding the IP

The RPi will need a few minutes on its first boot before it will connect to your network. You should then be able to find the RPi IP address in a mobile app like "Fing" or a similar IP scanner. The IP address will have the same prefix as your computer, but with a different ending. It probably also be Named "Octoprint" and/or "Raspberry Pi" or a variation of this. Common local IP addresses are 10.0.0.XXX or 192.168.0.XXX.

We can unfortunately not cover WiFi connection issues. Please see Octoprint's own resources.

Launching and configuring Octoprint

Open your browser and type in either "octopi.local" or the IP address of the RPi. You may be greeted with a welcome wizard. Please go through it and add a printer profile. Then we need to configure the Printer profile. 

Click the Settings-wrench in the top right (purple arrow). Here you can configure your profile, install plugins, and other settings (green square).

Select "Printer profiles" and click the pen icon (purple square) to edit. Under "Print bed & Build volume", change the values in the table below. All other values can be left to default. This will only affect Octoprint's control over your printer, and will not affect sliced G-codes.

 Form FactorOriginHeated BedWidthDepthHeightCustom Bounding Box
MK3SRectangularLower leftYes250mm210mm210mmX: 0/250, Y: -4/210, Z: 0/210
MINIRectangularLower leftYes180mm180mm180mmX: 0/180, Y: -3/180, Z: 0/180
If you are using Octoprint with the Original Prusa MMU2S/MMU3 you will also have to set "Number of extruders" to 5, and tick the checkbox for "Shared nozzle".

For RPis connected by USB, you can leave 'Serial Port' and 'Baudrate' on "AUTO" (blue square), and click the Connect button. Congratulations! You are now ready to use Octoprint with your printer. Octoprint will ask if you wish to update. Do so now, before installing any plugins.

Installing plugins

Running Raspberry Pi on your printer is sometimes called having a headless system, as there is no screen directly connected to the Pi board. Whenever you move your printer to a different network (and have edited octopi-wpa-supplicant.txt for the new network) or forget the printer's IP address, there is a plugin that will show the IP address on the printer's screen.

IpOnConnect may not work with the Original Prusa MINI.

Open your OctoPrint's web interface. Open Settings and in the left column find "Plugin manager", Scroll down click on "Get More..." (purple arrow) and search for "IPonConnect". Click install. After installation, a pop-up will prompt you to Refresh the page. Click "Refresh".

Turn the printer off and on again by flipping the switch on the side. Give it a few minutes and you should see the IP address on the display. Note that if you enter the printer's menu or insert an SD card, the IP address can disappear from the screen and you have to reboot the printer to see it again.

A lot of Plugins are not recommended when running Octoprint from an RPi Zero, due to its weak processor. Video streaming is one such function.


As we do not develop Octoprint, we can not cover all aspects of use. For that, we suggest checking out Octoprint's own resources. However, we recommend checking out our guide covering:

Below is a list of Octoprint plugins you might find useful or cool:

  • Simple Emergency Stop - Button on UI to stop everything immediately.
  • NavBar Temp - Temperature is shown in the navigation bar.
  • Heater Timeout - Shuts off heaters after set duration when idle.
  • OctoLapse - Better timelapse
  • Themeify - Cool (mostly dark) themes for the UI.

Configure RPi Zero W GPIO

To use RPi Zero/2 W connected directly to an MK3/S+ GPIO, you must change a setting in the printer's menu and configure how the Pi handles serial communication. By default, OctoPrint does not use the Raspberry Pi GPIO pins for Serial-communication. You configure this by connecting to it over SSH. This part only applies to the Raspberry Pi Zero/2 connected by GPIO directly to the MK3S Einsy mainboard.

Printer setting

First, to use the GPIO pins for connecting to the printer, activate the RPi port (LCD menu -> Settings -> RPi port and set it to "On").

Using SSH

The Octoprint image which you flashed should have SSH (Secure SHell) enabled. SSH is a way to have remote command over a device after inputting a hostname (what you called the RPi) and password. Make sure the RPi and your computer are connected to the same network and use the credentials below.

On Windows:

Open PuTTY and input "hostname@your_IP_address" (Example '[email protected]') to the Host Name field (green square). Most users can leave 'Port' number to 22. Make sure 'Connection type' is "SSH" and click Open (purple arrow).

On Mac:

An SSH client is built into Terminal. Open Terminal and type the following: 

ssh hostname@your_pi_address

In the console, you will be asked for a password. Input your password. No characters will appear as you type. Hit enter and you will have shell-command over your RPi.

On Linux:

Most popular distros also have an SSH Client installed and you connect the same way as on Mac. However, for all edits except changing the super-user password of the RPi, you can locate and edit the files using a card reader, from your desktop environment. Built-in card readers may not work on virtual machines. Use a USB card reader.

The first time you connect to the RPi by SSH, you may get a security warning that a "Server host key is not in cache". Make sure the IP you are connecting to is correct and accept proceeding with the connection by clicking Yes.

In the console, you will be asked for a password. Input your password. No characters will appear as you type. Hit enter and you will have shell-command over your RPi.

Using the command sudo raspi-config in the Terminal brings you a tool to change WiFi network and password, as well as the main password of the Pi.

Swapping ports used by GPIO and Bluetooth

This part only applies to the Raspberry Pi Zero connected by GPIO directly to the MK3S Einsy mainboard. From now on the RPi Zero must be connected to the printer.

Two config files must be updated and a serial port added, over SSH. Some of the following codes are taken from a thread in our forum (Shout out to Scott.w12:). 

The first thing to enable serial connection is to swap ports used by the GPIO (soldered pins) and the internal Bluetooth chip. We need to add a line in the config file on the boot partition.

sudo nano /boot/config.txt

With the down-key, move the cursor to the very end and add:


Press Ctrl+X to exit the Nano text editor. Press "Y" to save and hit enter to confirm the file name.

For Raspberry PI Zero 2:

If you experience connection or read/write issues, add the following line to the same file.


For good measure you can also disable Bluetooth services globally with the following Terminal commands:

sudo systemctl disable hciuart.service

sudo systemctl disable bluetooth.service

Disabling the serial console

Moving to another config file, where part of the code must be deleted to disable the serial console.

sudo nano /boot/cmdline.txt

Look for the following string (text) and delete it.


Rebooting RPi

For all changes to take effect, enter the following command to reboot the RPi.

sudo reboot

Adding a serial port to Octoprint

The last part of the configuration is in the web interface. Open your browser and type either "octopi.local" or the IP address of the RPi Zero W. You might be greeted with the welcome wizard, please go through it first.

As soon as you arrive at the home screen, open "Settings" by clicking the wrench. Then head to "Serial Connection", and insert the line below to "Additional serial ports" (green square).


Save the change and reboot OctoPrint. After reboot, select the new port (purple arrow) and connect to your printer (blue box). Also, tick "Save connection settings" and "Auto-connect on server startup" for your convenience.

The Raspi Zero is not a powerful device! It may be advisable to now remove pre-installed plugins, like "G-Code analyzer", to improve performance and reduce CPU usage. 
Was this article helpful?



Still have questions?

Still have questions?

If you have a question about something that isn't covered here, check out our additional resources.
And if that doesn't do the trick, you can send an inquiry to [email protected] or through the button below.

Contact us