Setting up a Development environment

Obtaining, building and running the source

This describes the general, platform agnostic 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 a virtual environment in the checked out source folder 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 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,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

  • build the documentation running sphinx-build -b html . _build in the docs folder – the documentation will be available in the newly created _build directory. You can simply browse it locally by opening index.html

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 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:

  • The current Python 3.8 Windows x86 executable installer

    • make sure to have the installer add Python to the PATH and have it install pip too

    • it’s recommended to install Python 3 into C:\Python3 - if you select different install locations please substitute accordingly

    • it’s also recommended to install for all users

  • Build Tools for Visual Studio 2019

    • install “C++ build tools” and ensure the latest versions of “MSVCv142 - VS 2019 C++ x64/x86 build tools” and “Windows 10 SDK” are checked.

  • Git for Windows

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
python -m pip install --upgrade pip
python -m 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 pip

    • python -m ensurepip --upgrade

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

    If desired, repeat for any other additional Python venvs (e.g. different versions).

  • 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 virtual environments (e.g. various Python 3 versions), 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.

Visual Studio Code (vscode)

  • Install Visual Studio Code from code.visualstudio.com

  • Open folder select OctoPrint checkout folder (e.g. ~/devel/OctoPrint or C:\Devel\OctoPrint)

  • Create a directory .vscode if not already present in the root of the project

  • Create the following files inside the .vscode directory

    settings.json
    {
        "python.defaultInterpreterPath": "venv3/bin/python",
        "python.formatting.provider": "black",
        "python.formatting.blackArgs": [
            "--config",
            "black.toml"
        ],
        "editor.formatOnSave": true,
        "python.sortImports.args": [
            "--profile=black",
        ],
        "[python]": {
            "editor.codeActionsOnSave": {
                "source.organizeImports": true
            }
        },
        "python.linting.pylintEnabled": false,
        "python.linting.flake8Enabled": true,
        "python.linting.enabled": true
    }
    
    tasks.json
    {
      "version": "2.0.0",
      "tasks": [
        {
            "label": "clean build artifacts",
            "type": "shell",
            "command": "python ./setup.py clean"
        },
        {
            "label": "build docs",
            "type": "shell",
            "command": "sphinx-build -b html ./docs ./docs/_build"
        }
      ]
    }
    
    launch.json
    {
      "version": "0.2.0",
      "configurations": [
          {
              "name": "OctoPrint",
              "type": "python",
              "request": "launch",
              "module": "octoprint",
              "args": [
                  "serve",
                  "--debug"
              ],
              "cwd": "${workspaceFolder}/src",
              "preLaunchTask": "clean build artifacts"
          }
      ]
    }
    

In the terminal install the python extension by running this command:

code --install-extension ms-python.python

In vscode terminal, or with venv active install code formatter black and linter flake8 by running:

python -m pip install -U black flake8 flake8-bugbear

Summary of vscode config:

  • Pressing F5 will now start OctoPrint in debug mode

  • Your terminal inside vscode uses the virtual python environment

  • Saving a file will run an auto formatter and import sort

  • Ctrl+Shift+B can be used to run the build docs task to rebuild the documentation