FAQ

Gina Häußge edited this page Jan 19, 2017 · 107 revisions

Table of Contents


General

I have a problem with my OctoPi installation...

Please refer to the OctoPi Github project for any problems you have with the SD card image OctoPi.

While this FAQ also contains a section about OctoPi specific frequently asked questions, this is just for you convenience. This FAQ is mainly about OctoPrint, which is the host software that talks to your printer. OctoPi - the custom distribution that includes said software among other things - is a project of itself maintained by Guy Sheffer. You are welcome to discuss all things OctoPi related on the Mailinglist or in the G+ community, but this Github project you are looking at here is the one of OctoPrint, so please help to keep things manageable.

In short: Before opening any tickets on this project's tracker here, first make sure it's really related to OctoPrint (problems with the web interface, connection or other communication issues with your printer, etc) and not just about the SD card image you installed to get up and running quickly (download problems, flashing problems, webcam support, network connectivity, software versions including the version of OctoPrint, etc).

Does OctoPrint support Makerbot or Flashforge printers?

There is a plugin that adds support for Makerbot (except for 5th gen) and FlashForge printers. It is OctoPrint-GPX by @markwal. Makerbots up to Gen5 and clones talk s3g/x3g instead of Gcode. That's why you print the x3g file instead of the gcode file. GPX is a tool that maps from gcode to x3g. The OctoPrint-GPX plugin wraps GPX for two-way printer communication.

You can try it out now, if you are running OctoPrint 1.2.0 or above. See the instructions on OctoPrint-GPX.

You may also want to take a look at BotQueue or switch to an opensource printer (those have way better community support too). For my own printer choice, I prefer to refrain from supporting a company with business ethics like that.

I want to access my OctoPrint installation from the internet, how do I do that?

First of all: Don't even think about doing that without enabling Access Control! I can't stress enough how important it is to SECURE YOUR PRINTER when you want to make it accessible from the internet (or any public/untrusted network for that matter). So please, before doing that, make sure you have Access Control configured and functioning.

Now with that being out of the way, you'll need to create a port forwarding on your router to the system (i.e. your Raspberry Pi) and the port you are running OctoPrint on. With a vanilla OctoPrint install that means you'll need to forward to port 5000. If you configured HAProxy to make OctoPrint accessible on port 80 (which you really should if you want to get the webcam stream to work too), you'll need to forward to port 80.

You'll also want to make sure you'll be able to reach your router/home network without having to know your current IP address. For this you'll want to use a Dynamic DNS service like http://www.noip.com/ or http://www.dnsdynamic.org. Those are services that will give you a named address like "yourName.no-ip.org". You'll need to get your router to update the address every time your IP changes (look for a "Dynamic DNS" setting in the router settings). If your router can't do it, you can also install ddclient on your RPi (see here).

Another way of doing this is to use a service such as ngrok or Pagekite. See each service's docs for specific instructions on tunneling ports.

I want to access my OctoPrint installation from the internet but I only want people I know to be able to see anything

In that case what you want is to restrict access to OctoPrint via common means (outside of OctoPrint) to establish network security.

Why that? Well, contrary to what you'd first think it would not be enough to just refuse to display anything of the usual information in OctoPrint's interface to anonymous users. First of all, that info would still be accessible on the websocket that is used for pushing that information to the frontend. Secondly, if you have a webcam configured and active, OctoPrint does not have any control over that at all (it just embeds it) so it can't possibly secure it. So if you really want to make sure that only you and the people you trust can get read-only access to your OctoPrint instance, you'll need to secure it one layer above OctoPrint in your network hierarchy.

At the very least you'll want to configure OctoPrint to be only accessible through a reverse proxy from the outside (e.g. by setting up haproxy in front of OctoPrint and forwarding its port 80 instead of OctoPrint's port 5000 -- OctoPi even already ships with haproxy in place!) and set up HTTP Basic Authentication for that. Better yet is to setup a VPN solution (Part 1, Part 2).

Keep in mind: OctoPrint is a print server. It is not a full fledged network security solution and it also does not try to be that since that would open up a whole different can of worms. Use established tools to achieve that please.

I've created a port forward for OctoPrint in my router, and I can now access OctoPrint from the internet just fine, but the webcam image doesn't work, what do I need to do?

If you want to access OctoPrint from the internet including webcam support, I strongly suggest you put haproxy in front of it and make everything reachable under port 80 (OctoPi users: No need to do anything, OctoPi already comes preconfigured this way, so hands off!), because otherwise getting the webcam to work from within and without your local network will be impossible. So just configure haproxy as described (or alternatively use another reverse proxy), then just forward only port 80 in your router and configure OctoPrint to use /webcam/?action=stream as Stream URL. This is not a typo, it is a relative URL that will make it work "magically".

Binding to port 80 I get "Permission denied" when starting OctoPrint

This is normal Unix/Linux behaviour. Only processes started by the user root are allowed to bind to ports below 1024.

Starting OctoPrint with sudo/as root tells me "You should not run OctoPrint as root!" - why?

This is intentional. It is generally not a good idea to run servers as user root, unless you really know what you are doing. No software (and this statement also includes OctoPrint) should ever be considered secure (although of course I do my best) and applications running as root on your system are potential attack vectors to really break stuff. If you do need to run OctoPrint as root (e.g. because you want to bind it to port 80 -- see above -- and running it behind something like HAProxy is not an option for whatever reason), take a look at the super secret startup option --iknowwhatimdoing. Note: I'm looking into privilege dropping to make running OctoPrint as user root safe.

Are there any other options to access OctoPrint from port 80?

You can use iptables(8) to create a portforward from OctoPrint's port to port 80. If OctoPrint is configured to use port 5000, you can use this command to forward to it from port 80.

# iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 5000

I can't get OctoPrint to connect to my printer

First of all make sure that you are trying to connect with correct port and baudrate settings. You might also want to try another host software like Printrun to make sure it is really OctoPrint that is causing the issue and not e.g. your printer. If you see something like Recv: ?+??Qj????)???Rj??Q??.V???????? when trying to connect, you probably are trying the wrong baudrate.

If you are running OctoPrint on a Linux machine it is possible that you won't be able to connect at 250000 baud out of the box - note that OctoPi supports 250000 baud. The reason is that a few Linux distributions (including older versions of Raspbian) still provide a PySerial version (which is used by OctoPrint to connect to your printer) that doesn't support 250000 baud (which isn't a "standard" baudrate so to say). You have two options to solve this for yourself:

  1. You can either reflash your printer to a firmware using a standard baudrate like 115200 (Hint: if you are running an Ultimaker and use Cura for slicing, such a firmware image can be found in Cura/resources/firmware/ in your Cura installation folder).
  2. You can patch the PySerial that is used by OctoPrint. For the latter please take a look at this post to the Mailinglist.

Note that - as of September 2014 - the Raspbian Wheezy image available from the Raspberry Pi Foundation (dated 2014-06-20) supports 250000 baud out-of-the-box.

If OctoPrint can't seem to connect to your printer although the printer appears to be properly responding, like e.g. in this example log of the serial communication:

Changing monitoring state from 'Offline' to 'Opening serial port'
Connecting to: /dev/ttyUSB0
Connected to: Serial<id=0x1d287d0, open=True>(port='/dev/ttyUSB0', baudrate=115200, bytesize=8, parity='N', stopbits=1, timeout=2.0,     xonxoff=False, rtscts=False, dsrdtr=False), starting monitor
Changing monitoring state from 'Opening serial port' to 'Connecting'
Recv: start
Recv: echo: External Reset
Recv: Marlin1.0.0
Recv: echo: Last Updated: Aug  6 2014 15:59:40 | Author: (Antonio castro, bq Hephestos)
Recv: Compiled: Aug  6 2014
Recv: echo: Free Memory: 3771  PlannerBufferBytes: 1232
Recv: echo:Hardcoded Default Settings Loaded
Recv: echo:Steps per unit:
Recv: echo:  M92 X80.00 Y80.00 Z4000.00 E100.47
Recv: echo:Maximum feedrates (mm/s):
Recv: echo:  M203 X250.00 Y250.00 Z3.30 E25.00
Recv: echo:Maximum Acceleration (mm/s2):
Recv: echo:  M201 X3000 Y3000 Z100 E10000
Recv: echo:Acceleration: S=acceleration, T=retract acceleration
Recv: echo:  M204 S1000.00 T1000.00
Recv: echo:Advanced variables: S=Min feedrate (mm/s), T=Min travel feedrate (mm/s), B=minimum segment time (ms), X=maximum XY jerk (mm/    s),  Z=maximum Z jerk (mm/s),  E=maximum E jerk (mm/s)
Recv: echo:  M205 S0.00 T0.00 B20000 X20.00 Z0.40 E5.00
Recv: echo:Home offset (mm):
Recv: echo:  M206 X0.00 Y0.00 Z0.00
Recv: echo:PID settings:
Recv: echo:   M301 P23.05 I2.00 D66.47
Send: M105
Send: M105
Recv: echo:SD init fail
Changing monitoring state from 'Connecting' to 'Closed'
Connection closed, closing down monitor

you should try to increasing your Connection timeouts in the Settings. Open your Settings page and in the "Serial Connection" section modify the values for "Connection Timeout" and "Communication Timeout" and possibly also the others if that doesn't help on its own:

Settings with Connection and Communication Timeouts highlighted

I see a lot of "communication timeout" messages in the log

Your printer is taking a bit too long to respond and so OctoPrint assumes it has gone AWOL and tries to tickle it back into replying. This is a known issue with the current communication layer and a fix is in progress, but in the meantime please try increasing the value for your "Communication Timeout" in the Settings. Open your Settings page and in the "Serial Connection" section modify the value for "Communication Timeout":

Settings with Communication Timeout highlighted

High CPU usage when mjpg-streamer is running

You may observe a high CPU usage on your OctoPrint host when mjpg-streamer is running. The diagnostic and the solution depend on the host type and on the webcam type.

The first step to solve this is to find out whether your webcam can directly output a compressed MJPEG stream, or if it can only output an uncompressed YUYV stream, by running the v4l2-ctl --list-formats command.

Here is an example of a Logitech webcam that can output a compressed MJPEG stream:

$ v4l2-ctl --list-formats
ioctl: VIDIOC_ENUM_FMT
    Index       : 0
    Type        : Video Capture
    Pixel Format: 'YUYV'
    Name        : YUV 4:2:2 (YUYV)

    Index       : 1
    Type        : Video Capture
    Pixel Format: 'MJPG' (compressed)
    Name        : MJPEG

If your camera can output a compressed MJPEG stream then you should not have any problems with high CPU usage when running mjpg-streamer, independently of the resolution chosen for the video stream.

However, most cheap USB webcams can only output an uncompressed YUYV stream, requiring mjpg-streamer to compress the video stream in software. On a Raspberry Pi, at a resolution of 640x480 this will result in a CPU usage of 60~80%. The solution is to step down the resolution to 320x240, resulting in a more reasonable CPU usage of 15~20%.

Halving the resolution results in a 4x reduction in CPU usage!

There is another caveat to using a Raspberry Pi as an OctoPrint host with mjpg-streamer, because it shares its USB bandwidth between all the USB peripherals and the Ethernet interface. When using mjpg-streamer at high resolutions, it is possible that the USB bandwidth available for the 3D printer serial interface is not sufficient for some prints. Again, the solution is to step down the video resolution.

And finally one last note about the Raspicam: it is capable of high resolution video streaming and the video compression is handled in principle by the VideoMax core in the Broadcom SOC (in other words, low CPU usage independently of the chosen resolution). But the caveat noted above still applies, with the same solution.

Adding buttons, event hooks, etc

Some things like custom controls, event hooks or system commands can only be configured within OctoPrint by directly editing it's config.yaml file at the moment. To quote from the wiki page about that file:

If not specified via the command line, the main configuration file config.yaml for OctoPrint is expected in its settings folder, which unless defined differently via the command line is located at ~/.octoprint on Linux, at %APPDATA%/OctoPrint on Windows and at ~/Library/Application Support/OctoPrint on MacOS.

YAML files are just simple text files that follow a special structure. If the file is not there yet, you can just create it using any text editor (make sure to name it config.yaml). When editing this file, please make sure to indent properly - two spaces per indentation level - and to not use tabs. If you are unsure of how the configuration format works, take a look at this primer on YAML syntax from the folks at ansible.com.

Why doesn't OctoPrint show me the current hotend position anywhere?

Because there's no way to get it from the printer without constantly querying it. It can be queried from the printer's firmware using M114, however in order for that information to be actually useful (e.g. in order to use it to trigger timelapse snapshots or do other nifty stuff) that command would have to be issued after any command sent to the printer and also in certain time intervals (since the printer might have moved the head due to being instructed to do that via an LCD menu or because it's printing from SD). The connection between OctoPrint and printer is limited to serial speeds, so 250000 baud at max. This transmission speed can already be maxed out now by just streaming gcode with a lot of short moves (e.g. curve segments). Imagine what would happen if OctoPrint added another command just to query the current head position from the printer after every command sent to the printer in such a scenario. The transmission rate would half, leading to blobby ugly prints, and all that just for some fancy display of where the head is right now or the possibility to trigger timelapse pictures always at the same position. That's just not worth the loss in quality.

Also be aware that OctoPrint can't track that information on it's own either by just adding up any moves sent via it - what about moves not triggered by itself but the printer (see above as to how)?

If you desperately need to have the printhead position displayed somewhere, take a look at a custom feedback command instead. But unless firmware starts to send this information with every acknowledgement of a received command, this won't get added to OctoPrint's core code due to a wrong cost/usefulness ratio.

My webcam is not working!

OctoPrint doesn't directly control your webcam. All it can do is embed an MJPG stream into the web interface and retrieve snapshots for the timelapse frames from the configured snapshot URL. If your webcam isn't working, it isn't something OctoPrint is at fault for or can fix.

Why is there no access control for the webcam in OctoPrint?

Because OctoPrint doesn't serve the webcam stream itself, it only embeds it and thus cannot possibly control access to it. Yes, it could just not display it for not logged in users, but that wouldn't keep anyone from just guessing your webcam's URL and just accessing the image that way. If you want to limit the access to your webcam, you need to do this a layer above OctoPrint, e.g. your reverse proxy ("haproxy") or your router's firewall.

An analogy: Your house is not safe from unwelcome guests just by hanging a big "keep out" sign on its door but leaving that door a) clearly visible behind the sign and b) unlocked. Just because the publicly accessible webcam is not embedded into a webpage doesn't make it less publicly accessible.

Proper network security management is not OctoPrint's job, and adding security by obscurity "features" such as just hiding otherwise accessible components like the webcam stream for anonymous users will just lead to people to think they don't have to properly secure their things when in fact they do, and this is something we here certainly don't want on our consciences.

OctoPrint doesn't work when connecting via HTTPS

Make sure the reverse proxy you are using for SSL termination is setting the X-Scheme header to https so OctoPrint knows it is being accessed through HTTPS and not HTTP and knows to generate the correct URLs.

Example: If you've set up your reverse proxy to serve OctoPrit on its address under https://<your server> you'll need to make it set the header X-Scheme: https in its requests to OctoPrint.

There are examples on the wiki on how to set everything up correctly. Alternatively, you can force OctoPrint to always assume HTTPS by editing the configuration file.

OctoPrint doesn't work when connecting via a different URL

Make sure the reverse proxy you are using to rewrite OctoPrint's URLs is setting the X-Script-Name header to your selected URL prefix so OctoPrint knows it is being accessed this way and knows to generate the correct URLs. Example: if you've set up your reverse proxy to serve OctoPrint on its address under http://<your server>/some/octoprint/installation you'll need to make it set the header X-Script-Name: /some/octoprint/installation in its requests to OctoPrint.

There are examples on the wiki on how to set everything up correctly. Alternatively, you can force OctoPrint to always assume a specific base URL by editing the configuration file.

I installed a broken plugin, how do I uninstall it again?

If you have installed a plugin which broke your installation so that the server doesn't come up anymore, you still can uninstall the offending plugin via the command line with pip:

pip uninstall <plugin>

Heads-up OctoPi users!!! For you it is ~/oprint/bin/pip uninstall <plugin>.

Note that <plugin> will usually be something like OctoPrint-<PluginName>, so for example if you wanted to uninstall the Autoselect plugin, you'd need to supply OctoPrint-Autoselect as the name to uninstall. If that doesn't work for you and you don't know the name, try pip freeze | grep OctoPrint (~/oprint/bin/pip on OctoPi!), it will show up in that list and you will hopefully be able to recognize it that way.

I'm using the Edge browser from Microsoft and...

... you are running into problems with OctoPrint? No surprise there, Edge still has some serious issues. Please use a stable browser, such as Chrome or Firefox instead.

OctoPrint is telling my printer to do wrong things

OctoPrint can only talk to your printer over its serial interface, and it can only tell it to do things that you tell OctoPrint to do. So if your printer is doing wonky stuff, its most probably not because OctoPrint is telling it to do that.

Wrong temperatures are set

OctoPrint sends temperature commands to the printer in exactly two cases: When you set a temperature on the temperature tab or when OctoPrint sends GCODE to the printer (e.g. a file to be printed or a GCODE Script). If you notice that your printer is set to wrong temperatures, check your slicer profile, your configured GCODE scripts and make sure you didn't accidentally set a temperature offset on the temperature tab.

The printer doesn't hold the temperature

That's a problem with your printer or the firmware of your printer. OctoPrint only sends a temperature set command (for when, see the previous section), it's your printer's job to correctly process that. If you see wild fluctuations in your temperature values, check your PID settings.

OctoPrint caused my printer's hotend to overheat!

OctoPrint doesn't tell your printer to go to temperatures that you didn't specify yourself, and it most definitely doesn't do that on its own. It's your responsibility to make sure you configure your slicer profiles so they don't set the hotend to 1000°C. Also make sure your firmware properly detects overheating and that your hotend's temperature probe and heater are properly secured.

OctoPrint made my printer move funny!

OctoPrint does not send move commands on its own. It only sends move commands that you either trigger yourself through the control panel or through streamed GCODE files. It's your printer's job to correctly interpret the received move commands, not OctoPrint's.

OctoPrint crashed my printer's head into the bed!

OctoPrint expects your firmware to take care of not driving the nozzle through the print bed when it sends it a home command - that is the job of your firmware. Make sure your endstops are wired correctly and that your firmware doesn't ignore them or the software endstops.

OctoPrint won't cancel when my printer is heating up!

You have to thank your firmware for that. Once your firmware is told to heatup to some temperature via M109 or M190, it basically enters a blocked state in which it is impossible to tell it to stop and return control via the serial interface. It pretty much puts its fingers in its ears and goes "lalala" until the requested target temperature is reached. If you hit "Cancel" in OctoPrint during that phase, OctoPrint will no longer continue sending any commands from your selected GCODE file to the printer, but it has to wait for the firmware to become responsive again before it can do anything.

Newer versions of the Marlin mainline version support a special command for canceling heatups (M108). Support for that throughout the thousands of firmware forks out there is way too limited yet though to rely on it being supported, and blindly sending it to a firmware version that doesn't support it might lead to unexpected behaviour.

tldr; This has technical reasons and cannot be changed currently. If you are in a hurry, try disconnecting and then reconnecting - on a lot of printers that will reset it and stop the heatup.

My SD prints get interrupted when I connect to my printer from OctoPrint!

Your printer has a controller board that resets on a new connection via the serial interface. A lot of them if not the majority do. There's nothing OctoPrint can do about that, it's a "feature" of your printer's hardware.

Since OctoPrint can't query the printer status without connecting to it, it also can't warn you about that before you hit connect (and displaying a warning every time you hit connect would be incredibly annoying to the majority of users who don't run SD prints outside of OctoPrint's control).

I forgot my OctoPrint password, how can I reset it?

You'll need to do this via the command line (e.g. by SSHing into your Pi or other machine that is running OctoPrint).

If you only have a single user setup in OctoPrint for which you forgot the password, the easiest way is simply resetting OctoPrint's user database and run the first time setup wizard again. The steps involved boil down to this:

  • remove ~/.octoprint/users.yaml
  • in ~/.octoprint/config.yaml replace firstRun: false with firstRun: true
  • restart the OctoPrint server and reload, you should be prompted to run the first time setup wizard again

If you are running OctoPi, you can use these commands to do all that:

rm ~/.octoprint/users.yaml
sed -i -e 's/firstRun: false/firstRun: true/g' ~/.octoprint/config.yaml
sudo service octoprint restart

If you have multiple users configured which you don't want to lose, you have two options:

  1. If you have another user that's configured with admin rights, ask them to reset your password via "Settings" > "Access Control"
  2. If you are the only admin user, do the following:
    • make a backup copy of users.yaml, e.g.: cp ~/.octoprint/users.yaml ~/.octoprint/users.yaml.bck
    • run the first time setup wizard again like explained above
    • open the the newly created users.yaml in a text editor - there will only be one entry, your new admin account, copy all of those lines
    • open the backed up version of users.yaml in a text editor, locate your user account therein and replace all its lines with those you just copied from the newly created users.yaml
    • delete the newly created users.yaml and rename your backup version - now modified with your new credentials - into users.yaml again, e.g. mv ~/.octoprint/users.yaml.bck ~/.octoprint.users.yaml
    • restart OctoPrint, you should then be able to login with your new password

When your printer is running the Marlin firmware...

I cannot select files on the printer's SD card

There existed a bug in Marlin that truncated the last character of commands sent to it for M23 (select file), M28 and M928 (start writing to file), M30 (delete file), M32 (select file and start printing it) and M117 (display message on printer's LCD) under certain conditions. In the case of the SD card handling commands, that leads to truncating the last character of the file's name, thus leading to problems further down the road (the file not being found etc).

Please make sure your version of Marlin includes this commit that fixes the truncation or at least replicates it. If you don't compile your firmware yourself, please urge whoever is maintaining it for you (the vendor of your 3D printer or someone else) to make sure that fix is included in it.

I cannot select and start printing files on the printer's SD card

Please refer to "I cannot select files on the printer's SD card", this is caused by the same issue.

I cannot write to files on the printer's SD card

Please refer to "I cannot select files on the printer's SD card", this is caused by the same issue.

When I delete a file from the printer's SD card, the communication stalls

There existed a bug in Marlin that caused the acknowledgement for the deletion of a file on the SD card to be formatted wrong (according to the common protocol -- the ok that finalizes the command processing was not on a different line but directly concatenated with the File deleted:<filename> message), making the mandatory ok look like it was part of the deleted file's name.

Please make sure your version of Marlin includes this commit which fixes the format of the acknowledgement or at least replicates it. If you don't compile your firmware yourself, please urge whoever is maintaining it for you (the vendor of your 3D printer or someone else) to make sure that fix is included in it.

Messages I sent to the printer via M117 are truncated

Please refer to "I cannot select files on the printer's SD card", this is caused by the same issue.

I have my printer set to a language that is not english and OctoPrint doesn't work properly

The communication between hosts (e.g. OctoPrint) and printer firmware (e.g. Marlin) underlies a agreed upon protocol, readable by humans and machines, in english language. Marlin used to contain code that sadly also translated the protocol messages into the selected display language (e.g. German, Spanish, Italian, ...).

Please make sure your version of Marlin includes this commit that returns the protocol messages back to english-only or at least replicates it. If you don't compile your firmware yourself, please urge whoever is maintaining it for you (the vendor of your 3D printer or someone else) to make sure that fix is included in it.


Updating OctoPrint

Changes in OctoPrint are not reflected on the UI

If you made changes to OctoPrint's config file (e.g. adding custom controls or system commands) and they do not show up in the UI, or if you've just updated OctoPrint/switched branches, first of all make sure you've restarted OctoPrint. The command is:

sudo service octoprint restart

If that doesn't help try clearing your browser's cache by doing a hard reload of the OctoPrint page in your browser: hold down the Shift key, then click the reload button. Clearing your browser cache is also required if you have stopped/started the mjpeg-streamer daemon.

Upon startup I get a weird "no module named..." error

If you get an error like the following upon startup:

Traceback (most recent call last):
  File "./run", line 21, in <module>
    import octoprint
  File "/home/pi/OctoPrint_git/src/octoprint/__init__.py", line 4, in <module>
    from octoprint.server import Server
  File "/home/pi/OctoPrint_git/src/octoprint/server/__init__.py", line 33, in <module>
    from octoprint.server.util import LargeResponseHandler, ReverseProxied, restricted_access, PrinterStateConnection, admin_validator
  File "/home/pi/OctoPrint_git/src/octoprint/server/util/__init__.py", line 15, in <module>
  File "/home/pi/OctoPrint_git/src/octoprint/server/util/tornado.py", line 24, in <module>
ImportError: No module named http1connection

then you've probably just switched around branches and have still some compiled Python binaries in your folder that Python is now wrongly using when starting OctoPrint instead of the correct code. The reason is that git is not aware of those files (since they are created by the Python runtime and not part of the git repository) and hence not automatically removed when switching branches.

In general you can (under Linux or Git Bash) get rid of the pyc files via the following commandline (see also this answer on Stack Overflow):

find . -iname '*.pyc' -print0 | xargs -0 --no-run-if-empty  rm

The same functionality has also been integrated into the clean command of the setup.py script on version 1.2.0 and up, so if you are running this, a simple

python setup.py clean

will be enough.

Alternatively, if you are absolutely sure that you have no custom changes made to your OctoPrint source folder, you can also instruct git to clean up anything that's not under source control via git clean:

git clean -d

Be careful though, that really will delete anything in the OctoPrint source directory that's not under source control (your config should not be located in there unless you've moved it there yourself, so don't worry about that), so be very sure that this is really what you want -- best do a dry-run first with git clean -d -n to be on the safe side.

I'll look into somehow making a safe clean up part of the setup script.

OctoPrint tells me I have an update available but I can't apply it

You probably are running OctoPrint on a setup you upgraded from an older version and simply haven't yet set it up to be able to update itself.

I can't ship this update configuration with OctoPrint's bundled Software Update plugin since there's no configuration that will work for everyone. People who installed OctoPrint themselves from source and did it differently than instructed would get a broken configuration if I shipped the OctoPi specific one.

If you already have setup everything and are running into an issue where you can't upgrade OctoPrint version 1.2.7, please see the next item.

I'm running 1.2.7, I tried to update to a newer version via the software update plugin but I'm still on 1.2.7 after restart!

There is a bug in 1.2.7 that prevents updating OctoPrint. It still detects that there's a new version available but upon trying to apply it all you get is a "update successful" message without anything actually happening. This bug is fixed in version 1.2.8 of OctoPrint and a plugin is provided for people running 1.2.7 that monkey patches the fix into 1.2.7 as well so an update via the software update plugin is possible.

Please see the release notes of 1.2.8 and specifically the section "A bug in 1.2.7 prevents directly updating to 1.2.8, here's what to do" for how to proceed.

I'm running 1.2.16, I tried to update to a newer version via the software update plugin but I get an error!

There is a a bug in 1.2.16 that might prevent updating OctoPrint if you have never saved the settings since installing 1.2.16. To fix this, simply open the Settings dialog and directly click "Save" (you don't have to change anything). That should get things working again.

For more details please see the release notes of 1.2.17.

How can I roll back to an earlier version after an update?

This assumes you want to downgrade your OctoPrint installation setup (which you set up following the general installation instructions or one of the setup guides on the wiki) to <old_version>. Your checkout folder is at /path/to/OctoPrint.

cd /path/to/OctoPrint
source venv/bin/activate
git fetch
git checkout master
git reset --hard <old_version>
python setup.py clean
python setup.py install

Then restart OctoPrint.

Note: If you did not follow the general installation instructions or any of the manual setup guides on the wiki, you might have to adjust the path to the virtual environment into which you installed OctoPrint (venv in the above steps).

OctoPi

How do I have to configure the webcam URLs in OctoPrint so that everything will work?

You don't have to configure anything. OctoPrint on OctoPi is already configure in a way that everything works out of the box, including access via port 80. So please just keep your hands off these settings ;)

For reference, the current configuration settings are:

  • Stream URL: /webcam/?action=stream (yes, no leading http, it's a relative path, it's correct this way!)
  • Snapshot URL: http://localhost:8080/?action=snapshot

How can I update the OctoPrint installation on my OctoPi image?

If you are running OctoPrint 1.2 stable and later on OctoPi 0.12 and later, OctoPrint will offer to update itself automatically via the bundled Software Update plugin when a new release is out. If you see there's an update available but can't apply it, please refer to "OctoPrint tells me I have an update available but I can't apply it" above.

Otherwise (or if you are running another branch than the stable master branch) you'll first need to ssh into your Pi or optionally connect it to an external keyboard and monitor and open a command line terminal.


DO NOT USE SUDO FOR ANY git OR python COMMANDS HERE! If you need sudo in order to update your OctoPi, you broke something on your OctoPi installation (probably by using sudo accidentally earlier) and you need to fix your permissions, not just blindly put sudo in front of commands until stuff works.

In order to fix your permissions, please do the following (yes, here sudo is used intentionally):

sudo chown -R pi.pi ~/oprint ~/OctoPrint

DO NOT EDIT BELOW INSTRUCTIONS TO CONTAIN SUDO FOR ANYTHING BUT THE SERVER RESTART!


  1. cd ~/OctoPrint
  2. git pull
  3. ~/oprint/bin/python setup.py clean
  4. ~/oprint/bin/python setup.py install
  5. sudo service octoprint restart

Also take a look at the section Updating OctoPrint of this FAQ!


Note: If you get an error about gnet.homelinux.com not being available during the git pull step, your OctoPi installation has a bug that happened during its build and that causes the checkout folder of OctoPrint to still point to the repository used during build for performance reasons. This can easily be fixed however:

cd ~/OctoPrint
git remote set-url origin https://github.com/foosel/OctoPrint.git

How can I revert to an older version of the OctoPrint installation on my OctoPi image?

You'll first need to ssh into your Pi or optionally connect it to an external keyboard and monitor and open a command line terminal.


DO NOT USE SUDO FOR ANY git OR python COMMANDS HERE! If you need sudo in order to update your OctoPi, you broke something on your OctoPi installation (probably by using sudo accidentally earlier) and you need to fix your permissions, not just blindly put sudo in front of commands until stuff works.

In order to fix your permissions, please do the following (yes, here sudo is used intentionally):

sudo chown -R pi.pi ~/oprint ~/OctoPrint

DO NOT EDIT BELOW INSTRUCTIONS TO CONTAIN SUDO FOR ANYTHING BUT THE SERVER RESTART!


  1. cd ~/OctoPrint
  2. source ~/oprint/bin/activate
  3. git checkout master
  4. git reset --hard <old_version>
  5. python setup.py clean
  6. python setup.py install
  7. sudo service octoprint restart

Replace <old_version> above by the version you want to downgrade to, e.g. 1.2.9. Step 3 is only recommended if you manually switched to a different branch before.

You'll want to click "Ignore" on the update notification. If you want to update to the current OctoPrint version at a later date again, you can do so via the Software Update plugin in the Settings dialog or manually.

How can I switch the branch of the OctoPrint installation on my OctoPi image?

You'll first need to ssh into your Pi or optionally connect it to an external keyboard and monitor and open a command line terminal.


DO NOT USE SUDO FOR ANY git OR python COMMANDS HERE! If you need sudo in order to update your OctoPi, you broke something on your OctoPi installation (probably by using sudo accidentally earlier) and you need to fix your permissions, not just blindly put sudo in front of commands until stuff works.

In order to fix your permissions, please do the following (yes, here sudo is used intentionally):

sudo chown -R pi.pi ~/oprint ~/OctoPrint

DO NOT EDIT BELOW INSTRUCTIONS TO CONTAIN SUDO FOR ANYTHING BUT THE SERVER RESTART!


  1. cd ~/OctoPrint
  2. git pull && git checkout devel
  3. ~/oprint/bin/python setup.py clean
  4. ~/oprint/bin/python setup.py install
  5. sudo service octoprint restart

To revert back to the master branch (or switch to any other branch you might want to try), substitute devel in the git checkout statement with master (or the name of the other branch).

Also take a look at the section Updating OctoPrint of this FAQ!


Note: If you get an error about gnet.homelinux.com not being available during the git pull step, your OctoPi installation has a bug that happened during its build and that causes the checkout folder of OctoPrint to still point to the repository used during build for performance reasons. This can easily be fixed however:

cd ~/OctoPrint
git remote set-url origin https://github.com/foosel/OctoPrint.git

I cannot update/switch branches, I get something about permissions

You probably misused sudo during an earlier update/branch switch. Never use sudo on OctoPi unless you need to restart the OctoPrint service. That means no sudo git ..., no sudo ~/oprint/bin/python ... etc. The only thing your need sudo for usually is sudo service octoprint restart.

If you get a permission error, you broke your file system permissions by using sudo wrongly. Yes, you could just ignore this and use sudo with everything from now on, but that will break things. Instead you need to fix those file system permissions (and yes, in order to do this you do need sudo):

sudo chown -R pi.pi ~/oprint ~/OctoPrint

After that, the update/branch switch instructions from above should a) work without permission errors and b) also get you a properly setup OctoPrint install.

I cannot install plugins, I get something about permissions

See above.

Why does OctoPi not load the WLAN?

As of OctoPi version 0.12.0 the method of which you setup the Wireless LAN has changed, now all you have to do is edit octopi-network.txt in the boot folder of the SD card from your computer or laptop. You can read about the full process in the OctoPi README

MacOS users: If you use Textedit to edit octopi-network.txt make sure to use plain text format and disable smart quotes in Textedit > Preferences, otherwise textedit will use none-compatible characters.

How can I change the webcam resolution on OctoPi?

See How can I change mjpg-streamer parameters on OctoPi?.

How can I change mjpg-streamer parameters on OctoPi?

You can change that via the config file octopi.txt. You can access it in two ways:

  • directly from the Pi: You can find the file at /boot/octopi.txt, just open it with your favorite text editor (e.g. nano), adjust it and then reboot your Pi (since the changes will only take effect at boot time)
  • from another computer: You can plug the OctoPi SD card into a card reader of your choice and plug that into another computer and open the card there. The file can then be found directly in the root directory of the SD card drive.

The file will look something like this:

### Configure which camera to use
#
# Available options are:
# - auto: tries first usb webcam, if that's not available tries raspi cam
# - usb: only tries usb webcam
# - raspi: only tries raspi cam
#
# Defaults to auto
#
#camera="auto"

### Additional options to supply to MJPG Streamer for the USB camera
#
# See https://github.com/foosel/OctoPrint/wiki/MJPG-Streamer-configuration
# for available options
#
# Defaults to a resolution of 640x480 px and a framerate of 10 fps
#
#camera_usb_options="-r 640x480 -f 10"

### additional options to supply to MJPG Streamer for the RasPi Cam
#
# See https://github.com/foosel/OctoPrint/wiki/MJPG-Streamer-configuration
# for available options
#
# Defaults to 10fps
#
#camera_raspi_options="-fps 10"

You can edit your camera's resolution and the refresh rate either via camera_usb_options (if it's an USB webcam) or camera_raspi_options (if it's the Raspberry Pi camera module). Just change the -r parameter to something different supported by your camera (-r <width>x<height>) and remove the # in front of the line or -- if you are running the RaspiCam -- add -x <width> -y <height> to the camera_raspi_options line and again remove the # in front of it. You can find the list of available options for USB webcams and the RaspiCam (they are different!) on the mjpg_streamer configuration page in the wiki.

An example for setting your USB webcam to 1280x720 px resolution and 20 frames per second would e.g. be this line:

camera_usb_options="-r 1280x720 -f 20"

An example for setting your USB webcam to 800x600 px resolution, 10 frames per second and YUVC mode (more CPU intensive, only use if your camera doesn't work otherwise or better yet get a camera that does) would be this line:

camera_usb_options="-r 800x600 -f 10 -y"

An example for setting your RaspiCam to the same parameters would be this line:

camera_raspi_options="-x 1280 -y 720 -fps 20"

Take note of the missing # in front in each of these examples!

I can't reach my OctoPi under octopi.local under Windows, why?

That .local part makes it a special address. Linux and MacOS already know how to understand it, Windows needs a little extra help.

You'll have to download the Bonjour Print Services for Windows and install them. Then make sure your Windows Firewall allows Traffic on UDP Port 5353 and grant internet access to the mDNSresponder.exe (part of the Bonjour support you just installed).


Note: This will only work if you home LAN is not set up to use .local as it's own LAN specific top level domain. This should usually not be the case, but if it is and you can't get your home LAN setup differently (e.g. by switching to .lan) you'll need to access your OctoPi instance by its IP address, sorry.


I need to change the port OctoPrint is listening on because I want to do a port forward and that port is already used in my router!

A proper router should actually allow you to create a port forward that forwards to your internal host "hostA" and port "x" from external port "y": route:y->hostA:x. So something like router:8080->octoprint:80 should be possible. Same goes for a scenario where you do something like router:8080->octopi1:80, router:8081->octopi2:80, etc.

These are standard network administration tasks your router should allow you to do. If it doesn't, it doesn't justify being called a router and you should complain to the manufacturer. OctoPrint and OctoPi are not a replacement for a proper network infrastructure.

That being said: Using OctoPi you are accessing OctoPrint on port 80 or 443 through haproxy, so you need to change the port number of that instead of the port number OctoPrint itself is listening on (which is port 5000 on localhost only). You'll need to edit /etc/haproxy/haproxy.cfg for that. There are lines that look like this:

frontend public
        bind *:80
        bind 0.0.0.0:443 ssl crt /etc/ssl/snakeoil.pem

You'll need to change the 80 in bind *:80 if you want to change the http port, and the 443 in bind 0.0.0.0:443 ssl crt /etc/ssl/snakeoil.pem if you want to change the https port. After a reboot, haproxy should then listen on the new port. Note that that means it will ONLY listen on those ports - you'll need to provide the new port when accessing your OctoPi instance from inside of your network now!