Download & Setup OctoPrint
OctoPi
Guy Sheffer maintains “OctoPi”, a Raspbian (and thus Debian) based SD card image for the Raspberry Pi that already includes OctoPrint plus everything you need to run it:
- OctoPrint plus its dependencies
- MJPG-Streamer for live viewing of prints and timelapse video creation, compatible with various USB webcams and the Raspberry Pi camera
Recommended hardware: Raspberry Pi 3B, 3B+, 4B or Zero 2. Expect print artifacts and long loading times with other options, especially when adding a webcam or installing third party plugins. Setups not using recommended hardware are not officially supported.
Please note that the Raspberry Pi Zero and Zero W are not recommended explicitly since severe performance issues were observed, caused by the WiFi interface when bandwidth is utilized (e.g. the webcam is streamed), negatively impacting printing quality. See also here. The Zero 2 however is recommended.
Installing OctoPi
OctoPi is available through the Raspberry Pi Imager, which you can use to download and setup OctoPi. You can install it yourself, or alternatively simply buy one of the available
Installing OctoPi using the Raspberry Pi Imager
🤚 Before you begin
Read and follow these instructions precisely.
-
If you haven’t already, download and install Raspberry Pi Imager on your computer
-
Find the OctoPi image under “Choose OS”, by selecting “Other Specific Purpose OS” > “3D printing” > “OctoPi” and then the “stable” version.
-
Open advanced options by clicking on the button with the gear, or by using the keyboard shortcut
ctrl
+shift
+x
and then:-
Configure your wifi options: Set your SSID, password and WiFi country.
-
Change the system password in “Set username and password” by entering a new password to use for the system user “pi”. This is not the password you’ll use for logging into OctoPrint but one that you’ll have to use to log into your Pi via SSH should you ever need to.
-
Optionally: Change the configured timezone in “Set locale settings”
-
Optionally: Change the hostname in “Set hostname”
-
-
Install the image to your SD card, then plug everything in to your Raspberry Pi and boot it up. Do not format the SD card after installing, even if prompted to do so. This will break the installation and you will have to start over!
-
Access OctoPrint from your browser via
http://octopi.local
or the hostname you chose (if your computer supports bonjour) orhttp://<your pi's ip address>
.https
is available too, with a self-signed certificate (which means your browser will warn you about it being invalid - it isn’t, it’s just not recognized by your browser).
Please also refer to OctoPi’s README, especially the “How to use it” section.
Alternative Initial Setup
If you decide against using the Raspberry Pi Imager, here are some alternative steps to get started:
-
Flash the image to your SD card through whatever alternative means you’ve chosen.
-
With the SD card still attached to your computer, set up the Wifi connection using the
octopi-wpa-supplicant.txt
file on the root of the installed card when using it like a thumb drive. Important: Do not use WordPad (Windows) or TextEdit (MacOS X) for this, those editors are known to mangle the file, making configuration fail. Use something like Notepad++, Atom or VSCode instead or at the very least heed the warnings in the file. If your computer doesn’t see the card right away after flashing, try ejecting and inserting it again. Do not format the SD card after installing, even if prompted to do so. This will break the installation and you will have to start over!Please also refer take a look at the full WiFi setup guide in the FAQ that also includes troubleshooting tips.
-
Plug everything into your Raspberry Pi and boot it up
-
Log into your Pi via SSH (it is located at
octopi.local
if your computer supports bonjour or the IP address assigned by your router), default username ispi
, default password israspberry
. Runsudo raspi-config
. Once that is open:- Change the password via “Change User Password”
- Optionally: Change the configured timezone via “Localization Options” > “Timezone”.
- Optionally: Change the hostname via “Network Options” > “Hostname”. Your OctoPi instance will then no longer be reachable under
octopi.local
but rather the hostname you chose postfixed with.local
, so keep that in mind.
You can navigate in the menus using the arrow keys and
Enter . To switch to selecting the buttons at the bottom useTab .You do not need to expand the filesystem, current versions of OctoPi do this automatically.
You also do not need to manually enable the RaspiCam if you have one, that is already taken care of on the image as well.
-
Access OctoPrint through
http://octopi.local
(if your computer supports bonjour) orhttp://<your pi's ip address>
.https
is available too, with a self-signed certificate (which means your browser will warn you about it being invalid - it isn’t, it’s just not recognized by your browser).
Please also refer to OctoPi’s README, especially the “How to use it” section.
Image Downloads
Raspberry Pi Imager will download the latest version of OctoPi for you, but if you want to download the images yourself you can do so here.
Stable OctoPi
756a7de8530777f40cd26d07d210ab1680fa49ef0ad795768a55000516c4018b
Raspberry Pi 3B, 3B+, 4B or Zero 2 strongly recommended, Raspberry Pi Zero/Zero W not officially supported, Raspberry Pi 5 currently unsupported!
Image compatible with Raspberry Pi 1A, 1A+, 1B, 1B+, 2B, 3A+, 3B, 3B+, 4B 1/2/4/8GB, Zero, Zero W, Zero 2 and 400.
Stable OctoPi with New Camera Stack
The same OctoPi image with the new camera stack can be found here:
87abc4cf58356d31a3c58bf8fdad8e1f22320cc4a82984d24d69f1eee76746a2
Raspberry Pi 3B, 3B+, 4B or Zero 2 strongly recommended, Raspberry Pi Zero/Zero W not officially supported, Raspberry Pi 5 currently unsupported!
Image compatible with Raspberry Pi 1A, 1A+, 1B, 1B+, 2B, 3A+, 3B, 3B+, 4B 1/2/4/8GB, Zero, Zero W, Zero 2 and 400.
OctoPi Nightlies
You can also get the 32bit nightlies here or the 64bit nightlies here.
Further resources
- For customizing OctoPi, take a look at CustoPiZer.
- Scripts to build the image yourself can be found in OctoPi’s Github repository.
Octo4a
Filip Grzywok maintains “Octo4a”, an Android app that allows you to use an Android based smart phone as an OctoPrint host. Root is not required!
Check out the Octo4a README for information on how to obtain the app, install and run it.
Video
There’s also a video guide on how to get Octo4a up and running by Thomas Sanladerer.
OctoPrint for Orange Pi
The people at Obico maintains an image suitable for use with the Orange Pi Zero 2 and the Orange Pi 3. You can find it here. Please report issues to Obico.
Docker
There’s also an official OctoPrint Docker image, octoprint/octoprint
. It is maintained
by Brian Vanderbush and team on GitHub.
Please refer to its entry on dockerhub for more details on usage and configuration.
octoprint_deploy (Linux)
octoprint_deploy is a guided script for installing OctoPrint and additional tools (video streamer, haproxy) on virtually any Linux system. It guides the user through creation of one or more OctoPrint instances. Creating multiple instances with the script allows control of multiple printers on a single piece of hardware. A variety of utilities improve the multi-instance experience, including automated creation of udev rules, syncing users between instances, and sharing file uploads between instances. It is compatible with OctoPi.
Maintained by Paul Paukstelis.
Windows Installer
OctoPrint-WindowsInstaller is a Windows installation wizard for OctoPrint. It is maintained by jneilliii. Please report issues here.
Installing manually
The generic setup instructions boil down to
- Installing Python 3, including pip.
- Creating a virtual environment somewhere:
python -m venv OctoPrint
- Installing OctoPrint into that virtual environment:
OctoPrint/bin/pip install OctoPrint
- OctoPrint may then be started through
./OctoPrint/bin/octoprint serve
or with an absolute path/path/to/OctoPrint/bin/octoprint serve
More specific setup instructions for the most common runtime environments can be found below.
Linux
For installing OctoPrint on Linux, please take a look at the setup instructions for Raspbian on the forum. They should be pretty much identical on other Linux distributions. See octoprint_install & octoprint_deploy (Linux) above for simplified scripted options.
Windows
For installing the OctoPrint server on a Windows system, please take a look at the setup instructions for Windows on the forum.
Mac
For installing the OctoPrint server on a Mac, please take a look at the setup instructions for MacOS on the forum.