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:

Stable Python 3 including pip, setuptools and virtualenv (currently supported: Python 3.7 up to 3.13)

Git

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 the python3 binary is available directly on your PATH. If it cannot be found on your PATH like this you’ll need to specify the full path 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

rebuild .css files from .less sources. See octoprint dev css:build --help

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

check whether there are newer versions of OctoPrint’s dependencies available via python setup.py scan_deps

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 3 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 python3 python3-pip python3-dev python3-setuptools python3-virtualenv git libyaml-dev build-essential

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

Todo

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

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:

Git for Windows

Latest *stable* Python 3 release from python.org

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 under individual components.

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

Optional but recommended tools

These are some tools that are recommended but not required to have on hand:

Visual Studio Code

Windows Terminal

Add the following profile to profiles.list in the settings, that will allow you to easily start Git Bash from the terminal:

{
    "guid": "{3df4550c-eebd-496c-a189-e55f2f8b01ce}",
    "hidden": false,
    "name": "Git Bash",
    "commandline": "C:\\Program Files\\Git\\bin\\bash.exe --login -i",
    "startingDirectory": "C:\\Devel",
    "tabTitle": "Git Bash",
    "suppressApplicationTitle": true
},

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.

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

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!

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": "venv/bin/python",
    "editor.formatOnSave": true,
    "[python]": {
        "editor.codeActionsOnSave": {
            "source.fixAll.ruff": "explicit",
            "source.organizeImports": "explicit"
        },
        "editor.defaultFormatter": "charliermarsh.ruff"
    },
    "python.linting.pylintEnabled": false,
    "python.linting.flake8Enabled": false,
    "python.linting.enabled": true,
    "python.testing.unittestEnabled": false,
    "python.testing.pytestEnabled": true,
}

tasks.json

{
  "version": "2.0.0",
  "tasks": [
    {
        "label": "clean build artifacts",
        "type": "shell",
        "command": "${command:python.interpreterPath} ./setup.py clean"
    },
    {
      "label": "install deps",
      "type": "shell",
      "command": "${command:python.interpreterPath} -m pip install -e .[develop,plugins,docs]"
    },
    {
      "label": "clean & install deps",
      "dependsOn": ["clean build artifacts", "install deps"]
    },
    {
        "label": "build docs",
        "type": "shell",
        "command": "${command:python.interpreterPath} -m 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 & install deps"
      }
  ]
}

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

code --install-extension ms-python.python

and the ruff extension by running this command:

code --install-extension charliermarsh.ruff

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

PyCharm

This is possibly outdated as I have switched to VisualStudio Code and might not work with current PyCharm versions.

“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. for separate Python 3 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: <OctoPrint venv folder>/bin/pre-commit (Linux) or <OctoPrint venv folder>/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. Python 3.7 and 3.8), 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.