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:
Python 3.8 including
pip
,setuptools
andvirtualenv
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 yourPATH
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) orsource 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 forgit 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) orsource 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:
The current Python 3.8 Windows x86 executable installer
make sure to have the installer add Python to the
PATH
and have it installpip
tooit’s recommended to install Python 2.7 into
C:\Python27
and Python 3 intoC:\Python38
- if you select different install locations please substitute accordingly
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
orC:\Devel\OctoPrint
)Register virtual environments:
(Linux, Windows) “File” > “Settings …” > “Project: OctoPrint” > “Project Interpreter” > “Add local …”, select OctoPrint
venv
folder (e.g.~/devel/OctoPrint/venv
orC:\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
orC:\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
orC:\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
environmentWorking directory: the OctoPrint checkout folder (e.g.
~/devel/OctoPrint
orC:\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 viapip 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.