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 (the Python 3 venv should be considered the primary one at this point):

    • 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]'

  • Set up the pre-commit hooks that make sure any changes you do adhere to the styling rules:

    • pre-commit install

  • Tell git where to find the file with revisions to exclude for git blame:

    • git config blame.ignoreRevsFile .git-blame-ignore-revs

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

  • trigger the pre-commit check suite manually from the checked out source folder via pre-commit run --hook-stage manual --all-files

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=python3 venv
source ./venv/bin/activate
pip install --upgrade pip
pip install -e .[develop,plugins,docs]
pre-commit install
git config blame.ignoreRevsFile .git-blame-ignore-revs

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:\Python38\python.exe venv
source ./venv/Scripts/activate
pip install --upgrade pip
pip install -e .[develop,plugins,docs]
pre-commit install
git config blame.ignoreRevsFile .git-blame-ignore-revs

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]
pre-commit install
git config blame.ignoreRevsFile .git-blame-ignore-revs

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 venv folder (e.g. ~/devel/OctoPrint/venv or C:\Devel\OctoPrint\venv).

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

  • 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: venv environment

    • 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].

  • Settings > Tools > File Watchers (you might have to enable this, it’s a bundled plugin), add new:

    • Name: pre-commit

    • File type: Python

    • Scope: Module ‘OctoPrint’

    • Program: $PyInterpreterDirectory$/bin/pre-commit (Linux) or $PyInterpreterDirectory$/Scripts/pre-commit (Windows)

    • Arguments: run --hook-stage manual --files $FilePath$

    • Output paths to refresh: $FilePath$

    • Working directory: $ProjectFileDir$

    • disable “Auto-save edited files to trigger the watched”

    • enable “Trigger the watched on external changes”

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.