Setting up a Development environment

Obtaining, building and running the source

This describes the general steps in obtaining, building and running. OS specific instructions can be found below.

  • Prerequisites:

  • Checkout the OctoPrint sources from their Git repository:

    • git clone https://github.com/OctoPrint/OctoPrint.git

  • Enter the checked out source folder: cd OctoPrint

  • Create virtual environments in the checked out source folder for both Python 2 and Python 3 to use for installing and running OctoPrint and its dependencies. Creating virtual environments avoids potential versioning issues for the dependencies with system wide installed instances:

    • virtualenv --python=python3 venv

    Note

    This assumes that python3 is a binary available directly on your PATH. If your Python 3 binary cannot be found on your PATH like this you’ll need to specify the full path to it here, e.g. virtualenv --python=/path/to/python3/bin/python venv

  • Activate one of the virtual environments:

    • source venv/bin/activate (Linux, macOS) or source venv/Scripts/activate (Git Bash under Windows, see below)

  • Update pip in the virtual environment:

    • pip install --upgrade pip

  • Install OctoPrint in “editable” mode, including its regular and development and plugin development dependencies:

    • pip install -e '.[develop,plugins,docs]'

When the virtual environment is activated you can then:

  • run the OctoPrint server via octoprint serve

  • run the test suite from the checked out source folder via pytest

To switch the activated virtual environment, simply activate the new environment as described above.

To deactivate the virtual environment and return to the system’s default Python: deactivate.

If you also want to be able to build the documentation that resides in the docs subfolder, you need to activate the Python 3 environment and install the docs dependencies as well:

  • source venv3/bin/activate (Linux, macOS) or source venv3/Scripts/activate (Git Bash under Windows, see below)

  • pip install -e .[develop,plugins,docs]

You can then build the documentation:

  • sphinx-build -b html . _build

Linux

This assumes you’ll host your OctoPrint development checkout at ~/devel/OctoPrint. If you want to use a different location, please substitute accordingly.

First make sure you have python 2 and 3 including their header files, pip, setuptools, virtualenv, git and some build requirements installed:

  • On apt based distributions (e.g. Debian, Ubuntu, …):

    sudo apt-get install python3 python3-pip python3-dev python3-setuptools python3-virtualenv python3 python3-virtualenv python3-dev git libyaml-dev build-essential

Todo

Using a Linux distribution that doesn’t use apt? Please send a Pull Request to get the necessary steps into this guide!

Then:

cd ~/devel
git clone https://github.com/OctoPrint/OctoPrint.git
cd OctoPrint
virtualenv --python=python2 venv2
virtualenv --python=python3 venv3
source ./venv2/bin/activate
pip install --upgrade pip
pip install -e .[develop,plugins]
source ./venv3/bin/activate
pip install --upgrade pip
pip install -e .[develop,plugins,docs]

You can then start OctoPrint via octoprint after activating one of the two virtual environments.

Windows

This assumes you’ll host your OctoPrint development checkout at C:\Devel\OctoPrint. If you want to use a different location, please substitute accordingly.

First download & install:

Open the Git Bash you just installed and in that:

pip install virtualenv
cd /c/Devel
git clone https://github.com/OctoPrint/OctoPrint.git
cd OctoPrint
virtualenv --python=C:\Python27\python.exe venv2
virtualenv --python=C:\Python38\python.exe venv3
source ./venv2/Scripts/activate
pip install --upgrade pip
pip install -e .[develop,plugins]
source ./venv3/Scripts/activate
pip install --upgrade pip
pip install -e .[develop,plugins,docs]

Mac OS X

Note

This guide is based on the Setup Guide for Mac OS X on OctoPrint’s Community Forum. Please report back if it works for you, due to lack of access to a Mac I cannot test it myself. Thanks.

Todo

This guide is not yet adapted to the concurrent use of Python 2 and 3 environments during development. Please send a Pull Request to get the necessary steps into this guide!

This assumes you’ll host your OctoPrint development checkout at ~/devel/OctoPrint. If you want to use a different location, please substitute accordingly.

You’ll need a user account with administrator privileges.

  • Install the latest version of Xcode suitable for your OS. For example, OS X 10.11 (El Capitan) requires Xcode 7.

  • Install Xcode’s command line tools:

    • xcode-select --install

    • sudo xcodebuild (ensure the license was accepted)

    • If you have more than one Xcode installed: sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

  • Install Homebrew and use that to install Python:

    • ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

    • brew install python

  • Install virtualenv

    • pip install virtualenv

  • Install OctoPrint

    cd ~/devel
git clone https://github.com/OctoPrint/OctoPrint.git
cd OctoPrint
virtualenv venv
source venv/bin/activate
pip install --upgrade pip
pip install -e .[develop,plugins]

IDE Setup

Todo

Using another IDE than the ones below? Please send a Pull Request to get the necessary steps into this guide!

PyCharm

  • “File” > “Open …”, select OctoPrint checkout folder (e.g. ~/devel/OctoPrint or C:\Devel\OctoPrint)

  • Register virtual environments:

    • (Linux, Windows) “File” > “Settings …” > “Project: OctoPrint” > “Project Interpreter” > “Add local …”, select OctoPrint venv2 folder (e.g. ~/devel/OctoPrint/venv2 or C:\Devel\OctoPrint\venv2).

    • (macOS) “PyCharm” > “Preferences …” > “Project: OctoPrint” > “Project Interpreter” > “Add …” > “Virtualenv Environment > “Existing Environment”, select OctoPrint venv2 folder (e.g. ~/devel/OctoPrint/venv2).

    Repeat for the venv3 folder.

  • Right click “src” in project tree, mark as source folder

  • Add Run/Debug Configuration, select “Python”:

    • Name: OctoPrint server

    • Module name: octoprint

    • Parameters: serve --debug

    • Project: OctoPrint

    • Python interpreter: Project Default

    • Working directory: the OctoPrint checkout folder (e.g. ~/devel/OctoPrint or C:\Devel\OctoPrint)

    • If you want build artifacts to be cleaned up on run (recommended): “Before Launch” > “+” > “Run external tool” > “+”

      • Name: Clean build directory

      • Program: $ModuleSdkPath$

      • Parameters: setup.py clean

      • Working directory: $ProjectFileDir$

    • If you want dependencies to auto-update on run if necessary (recommended): “Before Launch” > “+” > “Run external tool” > “+”

      • Name: Update OctoPrint dependencies

      • Program: $ModuleSdkPath$

      • Parameters: -m pip install -e .[develop,plugins]

      • Working directory: $ProjectFileDir$

      Note that sadly that seems to cause some hiccups on current PyCharm versions due to $PyInterpreterDirectory$ being empty sometimes, so if this fails to run on your installation, you should update your dependencies manually for now.

  • Add Run/Debug Configuration, select “Python tests” and therein “pytest”:

    • Name: OctoPrint tests

    • Target: Custom

    • Project: OctoPrint

    • Python interpreter: Project Default

    • Working directory: the OctoPrint checkout folder (e.g. ~/devel/OctoPrint or C:\Devel\OctoPrint)

    • Just like with the run configuration for the server you can also have the dependencies auto-update on run of the tests, see above on how to set this up.

  • Add Run/Debug Configuration, select “Python”:

    • Name: OctoPrint docs

    • Module name: sphinx.cmd.build

    • Parameters: -v -T -E ./docs ./docs/_build -b html

    • Project: OctoPrint

    • Python interpreter: venv3 environment (the docs build requires Python 3)

    • Working directory: the OctoPrint checkout folder (e.g. ~/devel/OctoPrint or C:\Devel\OctoPrint)

    • Just like with the run configuration for the server you can also have the dependencies auto-update when building the documentation, see above on how to set this up.

    Note that this requires you to also have installed the additional docs dependencies into the Python 3 venv as described above via pip install -e .[develop,plugins,docs].

To switch between Python 2 and 3, all you need to do now is change the Project Default Interpreter and restart OctoPrint. On current PyCharm versions you can do that right from a small selection field in the footer of the IDE. Otherwise go through Settings.

Note

Make sure you are running a PyCharm version of 2016.1 or later, or manually fix a debugger bug contained in earlier versions or plugin management will not work in your developer install when running OctoPrint from PyCharm in debug mode.