Install & Compatibility
Where this runs
tested against v9.7.0 · 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
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 11.5s · import 1.298s · 735MB
757MB installed
● package 757MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
vtk
✓ import vtk
This imports all VTK modules for convenience, suitable for interactive use or smaller scripts.
Specific VTK class
✓ from vtkmodules.vtkModuleName import ClassName
✗ from paraview import vtk; vtk.vtkSphereSource()
For better performance and faster startup in larger applications, import specific classes from their `vtkmodules` path. Importing `vtk` from `paraview` can lead to `AttributeError` for core VTK classes as it's a specific subset for ParaView.
This quickstart code creates a simple 3D sphere visualization using VTK's Python bindings. It sets up a sphere source, maps it to a graphical representation, creates an actor, and then displays it within a render window with user interaction capabilities.
import vtk
# Create a sphere
sphereSource = vtk.vtkSphereSource()
sphereSource.SetCenter(0.0, 0.0, 0.0)
sphereSource.SetRadius(1.0)
sphereSource.Update()
# Create a mapper
mapper = vtk.vtkPolyDataMapper()
mapper.SetInputConnection(sphereSource.GetOutputPort())
# Create an actor
actor = vtk.vtkActor()
actor.SetMapper(mapper)
# Create a renderer, render window, and interactor
renderer = vtk.vtkRenderer()
renderWindow = vtk.vtkRenderWindow()
renderWindow.AddRenderer(renderer)
renderWindowInteractor = vtk.vtkRenderWindowInteractor()
renderWindowInteractor.SetRenderWindow(renderWindow)
# Add the actor to the scene
renderer.AddActor(actor)
renderer.SetBackground(0.1, 0.2, 0.4) # Dark blue background
# Render and interact
renderWindow.Render()
renderWindowInteractor.Start()
Debug
Known issues
breakingVTK 8.x to 9.x Module System Rework in C++/CMake: Projects building VTK or C++ applications linking against VTK 8.x and migrating to 9.x will encounter significant changes in the underlying CMake module system. Old variables like `VTK_USE_FILE` are deprecated in favor of CMake targets. While primarily affecting C++ builds, this influences the overall ecosystem and may require adjustments in complex Python build environments or custom VTK module setups.fixUpdate CMake `find_package` calls and `target_link_libraries` to use VTK's new target-based module system (e.g., `find_package(VTK REQUIRED COMPONENTS CommonCore RenderingOpenGL2)` instead of `vtkCommonCore vtkRenderingOpenGL2`). Refer to the official 'Module Migration from VTK 8.2 to 9+' documentation.
affects: 8.x to 9.x
gotchaPerformance overhead with `import vtk`: While `import vtk` is convenient, it loads approximately 120 different VTK modules into memory. This can lead to noticeably slower startup times, especially for lightweight utility scripts or applications where processing itself is quick.fixFor performance-critical applications, or when only a few VTK classes are needed, prefer importing specific classes directly using `from vtkmodules.vtkModuleName import ClassName`. A script `Utilities/Maintenance/ModernizePythonImports.py` is available in the VTK source distribution to help convert existing code.
affects: All versions
gotchaPython Version Compatibility Lag: VTK is a compiled Python package and often lags behind the latest Python minor releases (e.g., 3.13, 3.14) in terms of pre-built wheels on PyPI. Users attempting to install `vtk` with very new Python versions might encounter 'No matching distribution found' errors.fixCheck VTK's official download page or PyPI for available wheels for your specific Python version. If a wheel is not yet available, consider using a slightly older, supported Python version or compiling VTK from source if advanced customization is required.
affects: Python 3.x with very recent minor versions (e.g., 3.13+)
gotchaChallenging Debugging for Python Wrappers: Debugging VTK-based Python scripts can sometimes be difficult due to potential silent failures or lack of verbose error messages from the underlying C++ library. This can lead to frustrating 'trial and error' debugging experiences.fixEnable debugging on individual VTK objects using `object.DebugOn()` to get more verbose output. For deeper issues, accessing debug symbols often requires building VTK from source with debug information enabled, which is not straightforward with `pip` installations.
affects: All versions
deprecatedDirect C++ API Exposure vs. Pythonic Access: Historically, VTK's Python wrappers directly exposed C++ member functions (e.g., `SetSize()`). While still functional, VTK 9.4 and later introduced more Pythonic access to properties and the ability to use keyword arguments in constructors, making code more readable and idiomatic Python. Older code using direct `Set*` methods is not broken but is less 'Pythonic'.fixFor new development, leverage the more Pythonic property access and constructor keyword arguments introduced in VTK 9.4+. Example: `actor.SetPosition(x,y,z)` can often be replaced by `actor.SetProperty(position=(x,y,z))` or similar patterns, depending on the class and property. Consult VTK 9.4 release notes for details.
affects: Pre-9.4 code patterns (still functional, but less idiomatic)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'vtk'
The VTK Python package is not installed in the current Python environment or is not accessible via the Python path.
fixRun `pip install vtk` to install the latest VTK Python bindings. If using a specific distribution or pre-compiled binaries, ensure they are correctly installed and configured for your Python environment.
Segmentation fault (core dumped)
This severe error in the underlying C++ VTK library is often caused by memory corruption, null pointer dereference, or issues with the graphics context, especially with large datasets, complex pipelines, or driver problems.
fixReview your VTK pipeline for incorrect object usage or premature deallocation, ensure up-to-date graphics drivers, and for headless environments, use a virtual frame buffer like `Xvfb` (e.g., `xvfb-run python your_script.py`).
AttributeError: module 'vtk' has no attribute 'vtkClassName'
This error typically occurs due to API changes between VTK versions, where a class or function has been renamed, moved, or deprecated, or when attempting to access a method not available on a specific VTK object.
fixConsult the VTK documentation for version 9.6.1 to find the correct class name or method signature. Ensure your code is compatible with your installed VTK version and check for any migration guides for older VTK code.
failed to create OpenGL context for VTK
VTK cannot initialize an OpenGL rendering context, usually due to missing or outdated graphics drivers, an unsupported GPU, or running on a headless server without a virtual display server (like Xvfb).
fixUpdate your graphics drivers, install necessary OpenGL development libraries (e.g., `mesa-utils` or `freeglut3-dev` on Linux), or use `Xvfb` for headless environments by running `xvfb-run python your_script.py`.
vtk window closes immediately
The VTK rendering window closes immediately because the Python script exits before entering an interactive event loop, which is necessary to keep the window open and responsive to user input.
fixEnsure that `renderWindowInteractor.Initialize()` and `renderWindowInteractor.Start()` are called at the end of your VTK visualization script to properly enter the event loop and maintain the window's display.
Upgrade
Version history
9.7.0latest on PyPI · released Aug 15, 2026
Audit
Dependencies
numpyoptionalEssential for efficient data handling and interoperability with VTK data structures, especially when converting between VTK data and Python arrays.