Setting up OctoPrint on MacOS


  • Must be performed with a user with Administrative privileges.

  • Requires the latest version of Xcode suitable for your OS X. For example, OS X 10.15.x (Catalina) requires Xcode 11.x. Specifically, this is to ensure that locally compiled components of Python libraries (such as pyobjc) can be installed successfully.

Check your current (active) Command Line Tools (CLT) version

  • Open up the macOS Terminal and check if and which version of the CLT you have with /Applications/ -version
    If you run the latest version, you can skip the next steps.

  • If you have, for whatever reason, more than one version of Xcode installed, switch to the latest one sudo xcode-select -s /Applications/

Install Xcode's Command Line Tools if necessary

  • xcode-select --install – this may ask you to accept the Xcode user license.
  • It doesn't hurt to also run sudo xcodebuild, to be sure the license acceptance process completed. If successful, you should see something like this: The directory /Users/YOURUSERNAME does not contain an Xcode project.

Install Homebrew and use it to install Python 3

Depending on which version of macOS you are running, Python 2.7 and/or Python 3.x may be already installed on your system. You can check this by simply running python -V in your Terminal.

  • If the shown version is 3.7 or higher, you're good to go and you can skip to the next section.

  • However, if you encounter 2.7 as your installed python interpreter, you have to install Python 3 manually. The easiest way is to use Homebrew, or brew for short. Check out the official web page: to learn more about it.

  1. Install brew by running:

    /bin/bash -c "$(curl -fsSL"
  2. Install the missing Python 3 versions:

    • Python 3: brew install python
    • After this stage, you may want to verify that it is correct with python -V again.

Install virtualenv

Note: for users with Anaconda or multiple python versions installed, make sure to use Python 3 from Homebrew. Homebrew uses this default directory: /usr/local/opt/python/libexec/bin. If needed, replace two of the below commands with /usr/local/opt/python/libexec/bin/python -m pip install virtualenv and /usr/local/opt/python/libexec/bin/python -m virtualenv venv.

We utilize virtualenv to maintain an isolated Python environment for OctoPrint development. This prevents other, global Python libraries or updates from breaking OctoPrint. While not strictly required, virtualenv can save us from headaches, down the road. See the virtualdev docs for more detail.

  • pip install virtualenv

Installing OctoPrint

Warning: Make sure the path to the location where you git clone, install and run OctoPrint does not contain spaces! Otherwise, Python will not run OctoPrint! This is especially important for users which use iCloud Drive to sync their Folders, as iCloud stores its content in /Users/YOURUSERNAME/Library/Mobile Documents/com~apple~CloudDocs/- too many fancy characters for Python!

You can check your locations path by running pwd in the Terminal inside the folder where you cant to execute the next steps inside.

If you don't need the sources (e.g. you just want to run OctoPrint, not develop against it) you can just install from PyPI:

  • mkdir OctoPrint
  • cd OctoPrint
  • virtualenv venv
  • source venv/bin/activate
    for bash and zsh shells (the default until 10.15, and the current default shell)
    csh, xsh, and fish scripts are also available in the bin folder

    You may want to check at this stage, that it is using the correct Python version, if you have more than one installed (python -V).
  • pip install -U pyobjc
  • pip install OctoPrint

Alternatively, can download and install from source:

:spiral_notepad: Note
This is not recommended unless you are planning to develop with OctoPrint. Pip installation is more than enough to keep up with updates.

  • git clone
  • cd OctoPrint
  • virtualenv venv
  • source venv/bin/activate
  • pip install -U pyobjc
  • pip install .

Running OctoPrint

Assuming that you are still inside the OctoPrint folder from above:

  • source venv/bin/activate
  • octoprint serve

or from any location (tap the Tab key (twice) on your keyboard after every / to get the next available path content suggestions shown)

  • /path/to/OctoPrint/venv/bin/octoprint serve

Accessing the web interface

Assuming that you haven't also installed haproxy you can get to the OctoPrint web interface from its default port of 5000 locally on your Mac via http://localhost:5000/.

Auto start on boot

Credit to Fahim Hossain on medium

Using a plist like this you can start octoprint when turning on the mac, even without logging in.

  • sudo nano /Library/LaunchDaemons/it.YOURNAME.octoprint.plist – edit this file
  • replace "USER" with your username (the short one on the left in the terminal)
  • assuming you have install OctoPrint in ~/OctoPrint
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">

This is a wiki post that anyone with trust level 2 or higher can contribute to. Please do so.

Originally part of the OctoPrint wiki on Github, migrated on 2019-11-13.


I'm getting
UnicodeDecodeError: 'ascii' codec can't decode byte 0xe2 in position 0: ordinal not in range(128)

Traceback (most recent call last):
File "", line 233, in
File "", line 159, in params
version = versioneer.get_version()
File "/Users/Nathan/OctoPrint/", line 1909, in get_version
return get_versions()["version"]
File "/Users/Nathan/OctoPrint/", line 1871, in get_versions
pieces = versions_from_lookup_f(lookup_data, root, verbose)
File "/Users/Nathan/OctoPrint/", line 1435, in git_pieces_from_lookup
File "/Users/Nathan/OctoPrint/", line 484, in run_command
else None))
File "/usr/local/Cellar/python@2/2.7.17_1/Frameworks/Python.framework/Versions/2.7/lib/python2.7/", line 394, in init
errread, errwrite)
File "/usr/local/Cellar/python@2/2.7.17_1/Frameworks/Python.framework/Versions/2.7/lib/python2.7/", line 1047, in _execute_child
raise child_exception
UnicodeDecodeError: 'ascii' codec can't decode byte 0xe2 in position 0: ordinal not in range(128)

python@2 was deleted from homebrew/core in commit 028f11f9e4:
python@2: delete (
EOL 1 January 2020.

Ran into the same issue myself; ended up using Miniconda to create a 2.7 environment. After doing that activated my 2.7 environment and I was able to install OctoPrint without issue.

You guys could try the latest dev rc of octoprint 1.4.0.
It comes with python 3 support :slight_smile:

pyenv is also an option. It’s homebrew-installable and lets you easily manage multiple python versions, which is still useful even in a 3-only world.

I would suggest that "solutions" like pipenv and pyenv are like inviting aliens from another planet to land and make camp. You soon find that they've begun teraforming the planet for their own favorite temperature of 102F rather than just leaving things the way they were before they arrived.

So some instruction might say "run pipenv clean" and then you find that some other project's virtual environment has been burned to the ground, figuratively-speaking.

There is already an accepted mechanism in place for this infrastructure. It's called virtualenv. Info

I was only recommending pyenv as a means of installing a Python version, which is all it does. pyenv doesn't replace virtualenv in this use case, it replaces homebrew's managed versions.

But since OctoPrint now runs on Python 3 just fine there's no reason for that guidance anyway, and the guide needs to be updated to just say to use homebrew for Python 3 as the method of least friction. (Except that in my experience, virtualenvs break when homebrew updates the Python version, since the symlinked python binary no longer exists...)

Actually that's another good reason to use pyenv: once you install a Python version it sticks around until you explicitly remove it.

Thank you for the tutorial! I used it to get my old High Sierra Late 2009 Macbook running OctoPrint on an Ender 3.

A couple issues with the tutorial:

  • You don't need the full Xcode, so that advice need not be followed. You just need to run xcode-select --install and install the xcode tools.
  • Homebrew's ruby installer is deprecated. Instead follow the directions on

Driver Installation
macOS needs a driver to communicate with the printer over USB. For the Ender 3 I used TH3D's driver package. I had to reboot after installing the driver.

For Macs running Catalina (or newer):
As of March 4, 2020, OctoPrint supports Python 3, so don't bother installing python@2.

For Macs running Mojave (or older):
Install Python 3 with brew install python. Use python3 when you need to invoke python. If you're unsure what python you're calling, run python --version to see the version info. You want to always use Python3.

For modules like pip and virtualenv, you'll want to run them with Python 3. Use python3 -m pip install virtualenv. This asks Python 3 to run the module pip. Similarly use python3 -m virtualenv venv

Preventing Sleep
I use an app called NoSleep to prevent my Macbook from going to sleep when I close the lid.

Setting up a Webcam using mjpeg_stream_webcam

  1. Run git clone
  2. cd mjpeg_stream_webcam
  3. python3 -m virtualenv -p python3 .env
  4. source .env/bin/activate
  5. pip install -r requirements.txt
  6. To start the streamer, run python If you want to access the stream from a networked computer, you must specify an ip such as python -i The Stream URL is then and the snapshot URL is

Is there an update for these instructions I am having issues getting this install to work on a Mac running Catalina. It seems like a lot of the steps are deprecated and out of date. I have been running Octoprint on a Pi 4 for a while but I want to create a multi instance Mac install to run my small farm of 10 machines.

I would also make a youtube video on the process to share with the community.

Any help would be greatly appreciated.

1 Like

@MMajewskiNet confirmed that what's up there now should work. Without access to a Mac myself, that's all I can give you.

In the spirit of odie5533, here's my experience with setting up OctoPrint for Mac:

Driver Installation
For my Monoprice Maker Select Plus (clone of Wanda i3 plus), I needed the CH340 driver for a 2010 MacBook Pro running High Sierra. I pulled them from this repo on GitHub.

Notes on HAProxy
Stealing the config file from the linux instructions, I discovered that the newest version of HAProxy doesn't support reqrep, which removed the port from the query (I think, my regex reading is rusty). The fix was substituting in http-request replace path for reqrep, and the rest worked without a hitch.
I also commented out the user and group configs, which hasn't screwed up anything (yet).

brew services continually starts haproxy if you start it through there (locked up my computer in 12 hours!), so I had to enable startup by hand.

Edit: The culprit was the daemon option haproxy. After disabling/removing that, it works as intended.

Instructions for setting up HAProxy

  1. Install HAProxy with brew install haproxy
  2. sudo nano /usr/local/etc/haproxy.cfg and edit it
  3. Set the service to start on boot with sudo homebrew services start haproxy
#cat /usr/local/etc/haproxy.cfg
        maxconn 4096
        #user haproxy
        #group haproxy
        log local0 debug

        log     global
        mode    http
        option  httplog
        option  dontlognull
        retries 3
        option redispatch
        option http-server-close
        option forwardfor
        maxconn 2000
        timeout connect 5s
        timeout client  15min
        timeout server  15min

frontend public
        bind :::80 v4v6
        use_backend webcam if { path_beg /webcam/ }
        default_backend octoprint

backend octoprint
        #reqrep ^([^\ :]*)\ /(.*)     \1\ /\2
	http-request replace-path ^([^\ :]*)\ /(.*)     \1\ /\2
        option forwardfor
        server octoprint1

backend webcam
        #reqrep ^([^\ :]*)\ /webcam/(.*)     \1\ /\2
        http-request replace-path ^([^\ :]*)\ /webcam/(.*)	\1\ /\2
	server webcam1

Setting a nice hostname
After setting up HAProxy, I wanted to set an easy to remember hostname to access OctoPrint.

You can do this via the terminal:
sudo scutil --set HostName 3dprinter.local

Or through System Preferences > Sharing > Computer Name > Edit... to change the bonjour name without changing the computer's name

Would it be possible to call this officially Mactoprint or octomac ?

No. It's still octoprint - no matter on which os it runs.


Seeing as it's not an "official" port like OctoPi...

Maybe we could do something with homebrew? Not sure if it makes things simpler or more complex, though.

What's the status on Python 3 compatibility? Python 2 has been removed from homebrew/core, so it's a hassle to get it installed. Is python 2 still recommended, or can the wiki be updated?

Octoprint itself got python 3 compatibility for a few months now.
But unfortunately just 65% of the plugins have been updated yet.
You can check them here

Updated 2020-11-03 to use Python 3 instead of 2 for installation.

Since I don't own a MacOS device to test this guide against, I would appreciate the next person to use it to feedback if it worked :slightly_smiling_face:

1 Like

I just finished following the instructions to install and it works perfectly. I really appreciate the work put into this. I haven't got to try a print yet but the web interface works and I can connect to the Octoprint.

I am just not totally clear on what I need to do to make this easier to run. For instance an icon I can click to run a script to make it all start.


1 Like

Assuming you don't want octoprint to start on boot, it's possible to create a small shell script to start on demand.

If Octoprint was installed at /Users/USER/Octoprint, replace USER with your username, or replace this part of the path with the location you installed Octoprint at. This will create a clickable icon on your desktop to start octoprint.

  1. Create a shell script with the command to start Octoprint.
    echo "/Users/USER/OctoPrint/venv/bin/octoprint serve" > ~/Desktop/octoprint.command
  2. Make the script executable
    chmod +x ~/Desktop/octoprint.command
  3. (Optional) Give the script a pretty icon
    a. Copy the octoprint image from the website
    b. Right click on the script, Get Info
    c. Click on the shell icon in the top left, and paste the Octoprint image
1 Like