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/foosel/OctoPrint.git
  • Enter the checked out source folder: cd OctoPrint
  • Create a virtual environment in the checked out source folder to use for installing and running OctoPrint and its dependencies (this avoids potential versioning issues for the dependencies with system wide installed instances): virtualenv venv
  • Activate the virtual environment: 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]

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 nosetests --with-doctest
  • build the documentation from the docs sub folder of the checked out sources via 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 including its header files, pip, setuptools, virtualenv, git and some build requirements installed:

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

    sudo apt-get install python python-pip python-dev python-setuptools python-virtualenv git libyaml-dev build-essential
    
  • On zypper based distributions (example below for SLES 12 SP2):

    sudo zypper ar https://download.opensuse.org/repositories/devel:/languages:/python/SLE_12_SP2/ python_devel
    sudo zypper ref
    sudo zypper in python python-pip python-devel python-setuptools python-virtualenv git libyaml-devel
    sudo zypper in -t pattern Basis-Devel
    

Todo

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

Then:

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

You can then start OctoPrint via ~/devel/OctoPrint/venv/bin/octoprint or just octoprint if you activated the virtual environment.

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/foosel/OctoPrint.git
cd OctoPrint
virtualenv venv
source ./venv/Scripts/activate
pip install --upgrade pip
pip install -e .[develop,plugins]

Mac OS X

Note

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

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/foosel/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)
  • “File” > “Settings …” > “Project: OctoPrint” > “Project Interpreter” > “Add local …”, select OctoPrint venv folder (e.g. ~/devel/OctoPrint/venv or C:\Devel\OctoPrint\venv)
  • Right click “src” in project tree, mark as source folder
  • Add Run/Debug Configuration, select “Python”:
    • Name: OctoPrint server
    • Script: path to run in the OctoPrint checkout folder (e.g. ~/devel/OctoPrint/run or C:\Devel\OctoPrint\run)
    • Script parameters: serve --debug
    • Project: OctoPrint
    • Python interpreter: the venv local virtual environment
    • Working directory: the OctoPrint checkout folder (e.g. ~/devel/OctoPrint or C:\Devel\OctoPrint)
    • If you want dependencies to auto-update on run if necessary: “Before Launch” > “+” > “Run external tool” > “+”
      • Name: Update OctoPrint dependencies
      • Program: $PyInterpreterDirectory$/pip (or $PyInterpreterDirectory$/pip.exe on Windows)
      • Parameters: install -e .[develop,plugins]
      • Working directory: $ProjectFileDir$
  • Add Run/Debug Configuration, select “Python tests” and therein “Nosetests”:
    • Name: OctoPrint nosetests
    • Target: Path, .
    • Project: OctoPrint
    • Python interpreter: the venv local virtual 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 on run of the tests, see above on how to set this up.
  • Add Run/Debug Configuration, select “Python docs” and therein “Sphinx task”
    • Name: OctoPrint docs
    • Command: html
    • Input: the docs folder in the OctoPrint checkout folder (e.g. ~/devel/OctoPrint/docs or C:\Devel\OctoPrint\docs)
    • Output: the docs/_build folder in the OctoPrint checkout folder (e.g. ~/devel/OctoPrint/docs/_build or C:\Devel\OctoPrint\docs\_build)
    • Project: OctoPrint
    • Python interpreter: the venv local virtual environment
    • 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

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.