Installation and Setup

This chapter covers installing the Whitebox Workflows QGIS plugin and its Python backend.

System Requirements

QGIS 4.0 or later (3.28+ may work but is not officially supported)
Internet connection (required for backend installation via pip)
macOS, Linux, or Windows

Install the QGIS Plugin

From QGIS Plugin Repository (Recommended)

Open QGIS
Go to Plugins → Manage and Install Plugins
Search for "Whitebox Workflows"
Click Install Plugin
Restart QGIS

From File (Manual Installation)

If you have a plugin .zip file:

Download or obtain the whitebox_workflows_for_qgis-*.zip file
Extract the zip to your QGIS plugins directory:
- macOS: ~/Library/Application Support/QGIS/QGIS4/profiles/default/python/plugins/
- Linux: ~/.local/share/QGIS/QGIS4/profiles/default/python/plugins/
- Windows: %APPDATA%\QGIS\QGIS4\profiles\default\python\plugins\
Ensure the directory structure is plugins/whitebox_workflows_qgis/ with __init__.py and metadata.txt directly inside
Restart QGIS

Install the Whitebox Workflows Backend

After installing the plugin, restart QGIS. The plugin will check for the whitebox-workflows Python package.

Option A: Install via Plugin Dialog (Easiest)

Open QGIS
If the backend is not installed, a dialog appears: "⚠️ Action Required — Install Whitebox Workflows Backend"
Read the installation instructions (or copy the command to clipboard)

exec("import runpy,sys\ntry:\n    import pip\nexcept ImportError:\n    import ensurepip\n    ensurepip.bootstrap(upgrade=True)\nsys.argv=['pip','install','--user','whitebox-workflows']\ntry:\n    runpy.run_module('pip',run_name='__main__',alter_sys=True)\nexcept SystemExit:\n    pass\nimport qgis.utils\nqgis.utils.unloadPlugin('whitebox_workflows_qgis')\nqgis.utils.loadPlugin('whitebox_workflows_qgis')\nqgis.utils.startPlugin('whitebox_workflows_qgis')\nprint('Whitebox Workflows backend installed and plugin reloaded.')")

Click Install to automatically download and install the backend using QGIS's bundled Python and pip
Wait for the installation to complete
The plugin automatically reloads with full access to all tools

Option B: Install via Command Line

If you prefer manual installation, run:

pip install whitebox-workflows

Or, if you have the QGIS Python environment:

# macOS/Linux (find the QGIS Python executable)
$(which python3) -m pip install whitebox-workflows

# Or explicitly use QGIS's Python if installed locally:
/Applications/QGIS.app/Contents/MacOS/Python/bin/python3 -m pip install whitebox-workflows

After installation, restart QGIS.

Verify Installation

Once the backend is installed, you should see:

The Processing Toolbox populates with 700+ Whitebox tools
No error messages in the QGIS message log
Whitebox tools appear in Processing → Toolbox → Whitebox Workflows

For Development and Local Testing

If you are a developer working with the source repository:

Checkout the whitebox_next_gen repository

Install the plugin locally by symlinking it into your QGIS plugins folder:

export QGIS_PLUGIN_DIR="<QGIS settings dir>/python/plugins"
mkdir -p "$QGIS_PLUGIN_DIR"
ln -snf "$PWD/crates/wbw_qgis/plugin/whitebox_workflows_qgis" \
  "$QGIS_PLUGIN_DIR/whitebox_workflows_qgis"

Install the backend using the automated installer or pip install whitebox-workflows
Changes to the plugin source are reflected immediately on QGIS restart

Troubleshooting

"Cannot find init.py or metadata.txt"

This error means the plugin zip was extracted incorrectly. Ensure your plugins directory contains:

plugins/
  whitebox_workflows_qgis/
    __init__.py
    metadata.txt
    bootstrap.py
    plugin.py
    ... (other files)

Not:

plugins/
  whitebox_workflows_qgis/
    whitebox_workflows_qgis/     ← Extra nesting
      __init__.py

This is a known issue on Windows when QGIS is installed via the OSGeo4W installer. Unlike the standalone QGIS installer, OSGeo4W does not include pip in its bundled Python by default. The symptom is an error like:

ImportError: No module named pip

or:

C:\OSGeo4W\bin\python.exe: No module named pip

Fix: Bootstrap pip into the OSGeo4W Python environment first, then re-run the backend installation.

Open the OSGeo4W Shell (search for it in the Windows Start menu)
Run the following commands to install pip:
```
python -m ensurepip
python -m pip install --upgrade pip
```
If ensurepip is unavailable, download and run the pip bootstrap script directly:
```
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python get-pip.py
```
Alternatively, follow the official OSGeo4W instructions for external Python packages at: https://trac.osgeo.org/osgeo4w/wiki/ExternalPythonPackages
Once pip is installed, run the Whitebox backend installation from the OSGeo4W Shell:
```
python -m pip install whitebox-workflows
```
Restart QGIS and the tools should populate normally.

Note: The standalone QGIS installer from qgis.org includes pip by default and does not require this step. If you encounter this issue frequently, consider switching to the standalone installer.

Other Backend Installation Issues

"Permission denied" — Try pip install --user whitebox-workflows
Network issues — Check your internet connection and proxy settings
For help — See Troubleshooting or contact support@whiteboxgeo.com

Whitebox Workflows for QGIS User Manual