Command Reference#
Command-line interface for building a VTK backend wheel from source.
pyvista-build vtk clones VTK, checks for the build tools, configures and
compiles it much like PyVista’s CI does, and writes a wheel. It works
on Linux, macOS, and Windows. See Building VTK for the eight steps in
detail, the module groups, portable Linux wheels, and the developer loop.
Examples#
Build VTK with the default tools, source, and configuration, printing every command as it runs:
pyvista-build vtk
Walk through the build one step at a time, confirming each step before any command runs:
pyvista-build vtk --interactive
Build a different backend, such as the cvista fork, or your own fork of VTK in its own build directory:
pyvista-build cvista
pyvista-build vtk --url https://github.com/me/vtk.git --ref my-branch --build-dir vtk-fork-build
Build without being asked, for scripts and CI. The list of what gets installed is still printed:
pyvista-build vtk --yes
Apply a named set of options from the backend’s manifest, here cvista’s
ci set, keeping any further flags on top (see Manifest Reference):
pyvista-build cvista --defaults ci
Build VTK’s master branch, or any tag, branch, or commit:
pyvista-build vtk --ref master
Customize the module groups, for example a wheel without the web export modules, or a minimal one with rendering only:
pyvista-build vtk --without web
pyvista-build vtk --minimal --with rendering
Customize the build itself: the build type, a CMake cache entry passed straight through, and the number of compile jobs:
pyvista-build vtk --build-type Debug -D VTK_ENABLE_LOGGING=OFF --jobs 8
Install the wheel into the current environment when the build finishes:
pyvista-build vtk --install
Build a portable Linux wheel inside a manylinux container (needs Docker, see Building VTK):
pyvista-build vtk --manylinux
Pass more of the environment and another directory into that container:
pyvista-build vtk --manylinux --env 'MY_*' --mount /data/sdk:/sdk:ro
Dry Run#
Print the commands a build would run without running any of them, which is the
quickest way to see what the eight steps do. For cvista, whose manifest lives
in its source tree, a dry run needs an existing checkout:
pyvista-build vtk --dry-run
Building backend: vtk
Dry run: every command is printed and nothing runs.
The build runs these eight steps:
1. Tools: check git, cmake>=3.22, ninja>=1.11, c++ compiler, auditwheel, patchelf,
setuptools, wheel. Install the missing auditwheel, setuptools, wheel into .venv
2. Source: clone https://gitlab.kitware.com/vtk/vtk.git at v9.7.1 into vtk-build/src
3. Build options: module groups rendering, io, web, matplotlib, parallel, serialization.
Options smp=Sequential. --with, --without, --minimal, and --opt NAME=VALUE change
them
4. Configure: cmake, Release build (--build-type) with Ninja, into vtk-build/build.
Compiler cache (--compiler-cache): ccache or sccache, whichever is on PATH
5. Build: compile with 4 parallel jobs (--jobs), logging to vtk-build/build.log
6. Wheel: package the wheel with setup.py bdist_wheel into vtk-build/build/dist
7. Repair: bundle the libraries the wheel links against with auditwheel, into
vtk-build/wheelhouse, so it installs on other machines. --no-repair skips it
8. Install: skipped. The install command is printed at the end, or pass --install
The wheel is built for .venv/bin/python.
Source, build tree, and wheel go in vtk-build. Compiling takes from minutes to over an
hour and needs several GB of disk.
─────────────────────────────────────── 1/8 Tools ────────────────────────────────────────
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
┃ Tool ┃ Found ┃ Status ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ git │ /usr/bin/git │ ok │
│ cmake>=3.22 │ /usr/local/bin/cmake (3.31.6) │ ok │
│ ninja>=1.11 │ /usr/local/bin/ninja (1.13.2) │ ok │
│ c++ compiler │ /usr/bin/c++ │ ok │
│ auditwheel │ - │ missing │
│ patchelf │ /usr/bin/patchelf │ ok │
│ setuptools (python) │ - │ missing │
│ wheel (python) │ - │ missing │
│ ccache/sccache (compiler cache) │ - │ missing, optional │
└─────────────────────────────────┴───────────────────────────────┴───────────────────┘
The build installs:
• auditwheel into .venv
• setuptools into .venv
• wheel into .venv
$ uv pip install --python .venv/bin/python auditwheel setuptools wheel
No ccache/sccache on PATH; rebuilds will be slow. Install one: apt install ccache (or:
dnf install ccache)
─────────────────────────────────────── 2/8 Source ───────────────────────────────────────
The source will be cloned from https://gitlab.kitware.com/vtk/vtk.git into vtk-build/src
(blob-less partial clone: history without file contents until needed).
$ git clone \
--progress \
--filter=blob:none https://gitlab.kitware.com/vtk/vtk.git vtk-build/src
$ git -c advice.detachedHead=false checkout v9.7.1 (in vtk-build/src)
Manifest: pyvista_build/manifests/vtk.toml
─────────────────────────────────── 3/8 Build options ────────────────────────────────────
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Group / option ┃ Value ┃ Description ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ rendering │ on │ OpenGL rendering, widgets, charts and text │
│ io │ on │ Extra readers and writers (scene import, Exodus, Xdmf2) │
│ web │ on │ Web export modules used by trame and the Jupyter │
│ │ │ backends │
│ matplotlib │ on │ Matplotlib-rendered math text and labels │
│ parallel │ on │ DIY2-based parallel filters (e.g. redistribution, ghost │
│ │ │ cells) │
│ serialization │ on │ Object serialization and .pyi stub files │
│ headless │ off │ No X: render through EGL or OSMesa, chosen at run time │
│ │ │ (Linux) │
│ --opt smp │ Sequential │ Threading backend for SMP-enabled filters │
└────────────────┴────────────┴──────────────────────────────────────────────────────────┘
Change the selection with --with/--without/--minimal and --opt NAME=VALUE.
───────────────────────────────────── 4/8 Configure ──────────────────────────────────────
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ Setting ┃ Value ┃ Flag ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ Build type │ Release │ --build-type │
│ Build tree │ vtk-build/build │ │
│ Python │ .venv/bin/python │ │
│ Compiler cache │ none (no ccache or sccache on PATH) │ --compiler-cache │
│ Version suffix │ (release) │ --version-suffix │
│ Extra cache entries │ (none) │ -D KEY=VALUE │
└─────────────────────┴─────────────────────────────────────┴──────────────────┘
$ cmake -Wno-dev \
-S vtk-build/src \
-B vtk-build/build \
-GNinja \
-UVTK_OPENGL_HAS_EGL \
-UVTK_USE_X \
-DCMAKE_BUILD_TYPE=Release \
-DPython3_EXECUTABLE=.venv/bin/python \
-DPython3_FIND_STRATEGY=LOCATION \
-DVTK_VERSION_SUFFIX= \
-DVTK_BUILD_DOCUMENTATION=OFF \
-DVTK_BUILD_EXAMPLES=OFF \
-DVTK_BUILD_TESTING=OFF \
-DVTK_DISPATCH_SOA_ARRAYS=ON \
-DVTK_USE_PCH=OFF \
-DVTK_WHEEL_BUILD=ON \
-DVTK_WRAP_PYTHON=ON \
-DVTK_GROUP_ENABLE_Rendering=WANT \
-DVTK_MODULE_ENABLE_VTK_IOImport=WANT \
-DVTK_MODULE_ENABLE_VTK_IOParallelExodus=WANT \
-DVTK_MODULE_ENABLE_VTK_IOXdmf2=WANT \
-DVTK_MODULE_ENABLE_VTK_WebCore=WANT \
-DVTK_MODULE_ENABLE_VTK_WebGLExporter=WANT \
-DVTK_MODULE_ENABLE_VTK_WebPython=WANT \
-DVTK_MODULE_ENABLE_VTK_RenderingMatplotlib=WANT \
-DVTK_MODULE_ENABLE_VTK_FiltersParallelDIY2=WANT \
-DVTK_BUILD_PYI_FILES=ON \
-DVTK_WRAP_SERIALIZATION=ON \
-DVTK_SMP_IMPLEMENTATION_TYPE=Sequential
─────────────────────────────────────── 5/8 Build ────────────────────────────────────────
4 CPU cores and 16 GB of memory detected; compiling with 4 jobs. A full VTK build takes
tens of minutes to hours.
$ cmake --build vtk-build/build --parallel 4
─────────────────────────────────────── 6/8 Wheel ────────────────────────────────────────
The wheel is written to vtk-build/build/dist.
$ python setup.py bdist_wheel (in vtk-build/build)
─────────────────────────────────────── 7/8 Repair ───────────────────────────────────────
Repairing bundles the libraries the wheel links against from outside it, so it installs on
other machines.
NOTE: on Linux the wheel is tagged for this machine's glibc; portable manylinux wheels
need a manylinux container.
$ auditwheel repair 'vtk-build/build/dist/vtk-*.whl' -w vtk-build/wheelhouse
────────────────────────────────────── 8/8 Install ───────────────────────────────────────
Not installed. To install later:
uv pip install \
--python .venv/bin/python \
--no-deps \
--force-reinstall 'vtk-build/wheelhouse/vtk-*.whl'
────────────────────────────────────────── Done ──────────────────────────────────────────
Source: vtk-build/src
Build tree: vtk-build/build
Dry run: nothing was built.
API Reference#
Show the output from pyvista-build --help.
Usage: pyvista-build BACKEND [OPTIONS]
Build a VTK backend wheel from source.
Asks once before starting, then builds with the defaults and prints every command as it
runs, with its output on one updating line (--verbose prints all of it, and the
environment variables each command sets). Anything the build has to install is listed
before that question, which covers it. --yes answers it. --interactive walks through the
steps, showing each setting and asking before running anything, and --dry-run prints the
commands without running them. --manylinux runs the build inside a manylinux container so
the Linux wheel installs on any machine.
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ --help (-h) Display this message and exit. │
│ --version Display application version. │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Parameters ───────────────────────────────────────────────────────────────────────────╮
│ BACKEND --backend Backend to build: one of cvista, vtk, or any name together │
│ with --url or --source. Defaults to $PYVISTA_VTK_BACKEND when │
│ that is set. │
│ --ref STR Git tag, branch or commit to build. Defaults to the │
│ manifest's release tag. │
│ --source PATH Existing source checkout to build instead of cloning. │
│ --url STR Git URL to clone instead of the backend's own, such as a │
│ fork. │
│ --with STR... Groups to enable, comma-separated or repeated. │
│ --without STR... Groups to disable, comma-separated or repeated. │
│ --minimal Enable only the required groups. [default: False] │
│ --opt STR... Set a manifest option, NAME=VALUE. Repeatable. │
│ --build-type CHOICE CMake build type: Release, RelWithDebInfo, or Debug. │
│ [choices: Release, RelWithDebInfo, Debug] [default: Release] │
│ --jobs INT Parallel compile jobs. Defaults to one per CPU core, at most │
│ one per 2 GB of memory. │
│ --define -D STR... Extra CMake cache entry, KEY=VALUE, applied last so it │
│ overrides the manifest. │
│ --clean Delete the build tree first. [default: False] │
│ --reconfigure Run cmake again even if the tree is configured. [default: │
│ False] │
│ --update Fetch, then check out --ref (or the release tag) in an │
│ existing checkout. [default: False] │
│ --compiler-cache CHOICE Compiler cache: auto, ccache, sccache, or none. auto uses │
│ whichever is on PATH, none builds without one. [choices: │
│ auto, ccache, sccache, none] [default: auto] │
│ --cache-dir PATH Compiler cache directory. Defaults to $CCACHE_DIR or │
│ $SCCACHE_DIR when set, else the cache tool's own default │
│ location, or <build-dir>/compiler-cache with --manylinux. │
│ --python PATH Python to build the wheel for and install it into. Defaults │
│ to the active virtual environment, else .venv in the current │
│ directory, else the Python running the command. │
│ --build-dir PATH Where source, build tree, and wheels go. Defaults to │
│ ./<backend>-build. │
│ --version-suffix STR Wheel version suffix. Defaults to dev0+g<sha>, or none when │
│ the checkout is at a tag. │
│ --repair --no-repair Bundle the libraries the wheel links against and tag it for │
│ other machines. --no-repair skips it. [default: True] │
│ --install Install the built wheel into this environment. [default: │
│ False] │
│ --yes -y Start, and install what the build needs, without asking. │
│ [default: False] │
│ --manylinux Build inside a manylinux container through Docker, for a │
│ portable Linux wheel. [default: False] │
│ --manylinux-image STR Container image for --manylinux. Defaults to manylinux_2_28. │
│ --env STR... Environment variable to pass into the --manylinux container, │
│ by name or fnmatch pattern such as MY_*. Repeatable. │
│ --mount STR... Extra directory for the --manylinux container, HOST:CONTAINER │
│ or HOST:CONTAINER:ro. Repeatable. │
│ --interactive -i Walk through the steps, confirming each one before any │
│ command runs. [default: False] │
│ --dry-run Print the commands and run nothing. [default: False] │
│ --verbose -v Print each command with its environment variables, and all of │
│ its output instead of one updating line. [default: False] │
│ --defaults STR Apply the manifest's [defaults.NAME] set; the other options │
│ win over it. │
╰────────────────────────────────────────────────────────────────────────────────────────╯