WhiteboxTools Python

2.3.6 verified Mon Apr 27 auth: no python

WhiteboxTools Python is an advanced geospatial data analysis platform that provides Python bindings for the WhiteboxTools library. Version 2.3.6 is current, updated to WhiteboxTools Open Core v2.3.0+. The library bundles WhiteboxTools binaries automatically but allows optional download. Release cadence is irregular, with recent updates addressing bugs and dependency improvements.

pip install whitebox

Common errors

error WhiteboxTools binary not found. Please set WBT_LINUX or WBT_WIN environment variable, or ensure an internet connection for automatic download. ↓

cause Automatic download failed (no internet, blocked, or wrong platform) and no local binary path is set.

fix

Set the environment variable WBT_LINUX (or WBT_WIN on Windows) to the path of the whitebox_tools executable.

error ModuleNotFoundError: No module named 'whitebox' ↓

cause The whitebox package is not installed.

fix

Run 'pip install whitebox' to install the package.

error AttributeError: module 'whitebox' has no attribute 'WhiteboxTools' ↓

cause Using an older version (pre-2.x) or import statement inconsistent.

fix

Use 'from whitebox import WhiteboxTools' (capital C, class) or 'from whitebox import wbt' for the instance.

Warnings

breaking WhiteboxTools backend updated to v2.3.0; some tool names or parameters may have changed. Check WhiteboxTools changelogs if existing scripts fail. ↓

fix Verify tool names and parameters against WhiteboxTools v2.3.0+ documentation; update scripts accordingly.

gotcha WhiteboxTools binary is downloaded automatically on first use. If behind a proxy or without internet, set WBT_LINUX or WBT_WIN environment variable to a local binary path. ↓

fix Set environment variable WBT_LINUX or WBT_WIN to the path of the whitebox_tools executable to skip download.

deprecated pkg_resources is deprecated; replaced with importlib.resources in v2.3.6. Should not affect end-users but may break custom wrappers depending on pkg_resources. ↓

fix Update any code relying on pkg_resources to use importlib.resources.

gotcha The 'wbt' object is a singleton instance of WhiteboxTools. Creating new instances (WhiteboxTools()) may cause conflicts if they share the same temporary directory. ↓

fix Use the pre-instantiated 'wbt' from whitebox import wbt. Only create WhiteboxTools() if you need separate configurations.

Imports

WhiteboxTools
wrong
```
import whitebox
```
correct
```
from whitebox import WhiteboxTools
```
'import whitebox' is valid but does not import the main class; you need to access whitebox.WhiteboxTools.
wbt
wrong
```
from whitebox import WhiteboxTools as wbt
```
correct
```
from whitebox import wbt
```
WhiteboxTools() is already instantiated as 'wbt' in the whitebox module; use 'from whitebox import wbt' for a ready-to-use instance.

Quickstart

Basic usage of WhiteboxTools via the pre-instantiated 'wbt' object. Replace file paths with actual datasets.

from whitebox import wbt
wbt.set_verbose_mode(True)
wbt.feature_preserving_smoothing(
    dem="/path/to/dem.tif",
    output="/path/to/smoothed.tif",
    filter=5,
    norm_diff=0.5,
    num_iter=3
)
print(wbt.run_tool('feature_preserving_smoothing', ['-i=/path/to/dem.tif', '-o=/path/to/smoothed.tif', '--filter=5', '--norm_diff=0.5', '--num_iter=3']))