Install & Compatibility
Where this runs
tested against v2.3.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.130s · 19.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.120s · 20MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
WhiteboxTools
✓ from whitebox import WhiteboxTools
✗ import whitebox
'import whitebox' is valid but does not import the main class; you need to access whitebox.WhiteboxTools.
wbt
✓ from whitebox import wbt
✗ from whitebox import WhiteboxTools as wbt
WhiteboxTools() is already instantiated as 'wbt' in the whitebox module; use 'from whitebox import wbt' for a ready-to-use instance.
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']))
whitebox_tools --version
Debug
Known issues
breakingWhiteboxTools backend updated to v2.3.0; some tool names or parameters may have changed. Check WhiteboxTools changelogs if existing scripts fail.fixVerify tool names and parameters against WhiteboxTools v2.3.0+ documentation; update scripts accordingly.
affects: <2.3.0 -> >=2.3.0
gotchaWhiteboxTools 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.fixSet environment variable WBT_LINUX or WBT_WIN to the path of the whitebox_tools executable to skip download.
affects: All
deprecatedpkg_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.fixUpdate any code relying on pkg_resources to use importlib.resources.
affects: >=2.3.6
gotchaThe 'wbt' object is a singleton instance of WhiteboxTools. Creating new instances (WhiteboxTools()) may cause conflicts if they share the same temporary directory.fixUse the pre-instantiated 'wbt' from whitebox import wbt. Only create WhiteboxTools() if you need separate configurations.
affects: All
Errors
Common errors & fixes
WhiteboxTools binary not found. Please set WBT_LINUX or WBT_WIN environment variable, or ensure an internet connection for automatic download.
Automatic download failed (no internet, blocked, or wrong platform) and no local binary path is set.
fixSet the environment variable WBT_LINUX (or WBT_WIN on Windows) to the path of the whitebox_tools executable.
ModuleNotFoundError: No module named 'whitebox'
The whitebox package is not installed.
fixRun 'pip install whitebox' to install the package.
AttributeError: module 'whitebox' has no attribute 'WhiteboxTools'
Using an older version (pre-2.x) or import statement inconsistent.
fixUse 'from whitebox import WhiteboxTools' (capital C, class) or 'from whitebox import wbt' for the instance.
Upgrade
Version history
2.3.6latest on PyPI · released Feb 23, 2025
Audit
Dependencies
whitebox-whiteboxtoolsoptionalOptional: WhiteboxTools binaries are downloaded automatically if not bundled. Set WBT_LINUX or WBT_WIN to custom path.