1.2. Installation

1.2.1. Virtual Environment

Before we will install groundwork, it would be great if we had a fresh and untouched Python installation. Luckily it is not necessary to do a complete new installation, because Python supports virtual environments.

These virtual environments are based on an already installed Python installation, but all additional installed packages not visible within the virtual environment.


groundwork supports Python 2.7 and >=3.3 only. Please make sure your installed Python Environment is correct. Creation

To create a new virtual environment, execute the following on the commandline:

python3 -m venv gw_venv

This will create the virtual environment gw_venv (groundwork virtual environment) in the folder gw_venv of the current working directory. Activation

To activate your new virtual environment, execute one of the following commands:

source gw_venv/bin/activate  # For Linux
gw_venv\Scripts\activate.bat # For Windows

After that, the prefix (gw_venv) should show up in front of your command prompt.

1.2.2. groundwork Installation

After activating your new virtual environment, we simply use pip to install groundwork:

pip install groundwork

The virtual environment version of pip is used which installs groundwork to the virtual environment. Alternative: Installation from source

If you want a installation from the latest groundwork source code, you need to clone the project repository and perform a development installation:

git clone https://github.com/useblocks/groundwork
cd groundwork
pip install -e .

pip install -e . sets only links from the source code to the used virtual environment. So changes on the code are directly available without any reinstallation (except if you have changed setup.py ).


Before executing pip install -e . please be sure that your working directory is the just cloned groundwork-folder! The “.” in the command stands for “current working directory”. Alternative you can give pip the complete path: pip install -e /my/folder/to/groundwork/.

Not sure what the correct path is? It must contain a setup.py file to be usable for installation. Packages for test execution and documentation building

For a normal user the just installed packages are enough to run groundwork and all related applications.

However, developers normally want also to run tests and maybe generate the documentation by their own. For this tasks additional python packages are needed, which are not needed for normal usage. Therefore these package are not part of the normal installation and must be installed by the developers.

Luckily these dependencies are also collected in one single file, so that it can be used as input for pip. Let’s install these packages to be prepared:

pip install -r docs/doc-requirements.txt
pip install -r code/test-requirements.txt

1.2.3. Tests

Finally let’s check if groundwork was installed correctly, by trying to execute the command groundwork:

>>> groundwork
Usage: groundwork [OPTIONS] COMMAND [ARGS]...

  --help  Show this message and exit.

  doc            Shows the documentation
  doc_list       List all documents
  doc_write      Stores documents as files
  plugin_list    List all plugins
  receiver_list  List of all signal receivers
  recipe_build   Builds a given recipe
  recipe_list    Lists all recipes
  signal_list    List of all signals

If you see the above output, congratulation! groundwork is installed and we can go on to examine the groundwork command in the chapter Usage.