Global Configuration

This page is the central reference for every process-wide setting in PyVista:

• Configuration Objects – runtime settings on pv.global_theme (plotting) and pv.global_config (everything else).

• Module-Level Flags – module-level attributes such as pv.OFF_SCREEN.

• Environment Variables – environment variables read when PyVista is imported.

• VTK Interface Controls – runtime controls for the VTK interface.

• Extension Registries – registration functions and entry points for extending PyVista.

• Inspecting the Environment – inspecting the active configuration with pyvista.Report.

Configuration Objects

Two singleton objects hold PyVista’s runtime settings. Plotting defaults live on pv.global_theme and all other settings live on pv.global_config. Both share the same machinery: attribute access, dict-style item access, and to_dict / from_dict round-tripping.

Plotting: The Global Theme

pv.global_theme is a Theme instance holding every plotting default: colors, fonts, window size, camera behavior, the Jupyter backend, and more. Assign to its attributes to change the defaults for all later plots:

import pyvista as pv

pv.global_theme.color = 'lightblue'
pv.global_theme.window_size = [600, 400]
pv.global_theme.smooth_shading = True

Swap the entire theme with pyvista.set_plot_theme() or the PYVISTA_PLOT_THEME environment variable, list the available names with pyvista.registered_themes(), and save or restore a customized theme with save() and pyvista.load_theme(). A theme can also be applied to a single plotter with pv.Plotter(theme=my_theme). Choose the notebook backend with pyvista.set_jupyter_backend(), and see Jupyter Backends for the backend registry.

See also

Plotting Themes

User guide for customizing and applying themes.

Themes

API reference for every theme class.

Core: The Global Config

pv.global_config holds the non-plotting settings and is the core counterpart of pv.global_theme:

import pyvista as pv

pv.global_config.validate_on_wrap = False

class Config

PyVista core configuration.

Holds process-wide settings that affect pyvista.core behavior. The singleton instance is exposed as pyvista.global_config. This is the sibling of pyvista.global_theme for plotting (rendering) settings. See Global Configuration for an overview of all global settings.

Examples

Download Python source code | Download Jupyter notebook

Disable the default array-length check performed by pyvista.wrap():

>>> import pyvista as pv
>>> pv.global_config.validate_on_wrap = False
>>> pv.global_config.validate_on_wrap = True  # restore default

See Also

pyvista.plotting.themes.Theme

Plotting counterpart, exposed as pyvista.global_theme.

property points_dtype: Literal['preserve', 'float32', 'float64'] | None

Return or set the points dtype used by filters and sources.

Many VTK algorithms generate single-precision points even when the input has double-precision points, and a few do the reverse, so the points dtype can change underneath you partway through a pipeline. This setting makes the dtype a property of the session rather than of whichever algorithm happens to run.

Where it is not None it is enforced everywhere PyVista wraps the output of a VTK algorithm, which covers every filter, every geometry and parametric source, and the generated points of ImageData and RectilinearGrid. Constructing a dataset keeps the array you pass, so pv.PolyData(points) has the dtype of points; the geometry factories are sources, so pv.Triangle(points) follows the setting.

None

The default. PyVista does not intervene and each algorithm produces whatever dtype it produces, which is the behavior of every release before 0.49.

'preserve'

A filter’s output points have the same dtype as its input points, so a filter never changes the dtype. This covers the meshes that store their points; ImageData and RectilinearGrid generate theirs from the origin and spacing, or from the coordinate arrays, so they constrain nothing. Sources have no input either, and keep the dtype VTK generates. A filter that builds one of those as an intermediate takes the dtype from it rather than from the input, so voxelize() and reconstruct_surface() still produce single precision from a double-precision mesh. Ask for 'float64' where the output dtype has to be certain.

'float32'

Every source and filter generates single-precision points, including the ones that would otherwise generate double precision.

'float64'

Every source and filter generates double-precision points.

Copying or recasting a dataset is not a source and keeps the points it was given, so mesh.copy() and mesh.cast_to_pointset() never change dtype.

Warning

A dtype can always be delivered; the precision behind it cannot. Some algorithms cannot run in double at all – vtkShrinkFilter has no precision setting – so they compute in single and their output is cast back up. The points are then float64 holding values that are only single precision, and calling points_to_double() on them recovers nothing: the digits went when the filter ran. A float64 points array is not on its own evidence of double-precision values.

Every such cast warns with PrecisionWarning, naming the algorithm, so the fabrication is never silent. Casting the other way does not warn: discarding digits below the input’s own representation error loses nothing that was there.

The setter accepts 'preserve', None, and anything numpy.dtype resolves to numpy.float32 or numpy.float64 (for example np.float64, 'double', or float).

Notes

An explicit 'float32' or 'float64' is requested from the algorithm first, via SetOutputPointsPrecision, so the computation itself is done in that precision wherever VTK supports it, and only the algorithms that ignore the request need their output cast afterwards. 'preserve' asks for nothing: VTK’s own default already matches the input for all but a handful, and requesting it anyway would widen more than the points for some filters.

That request reaches whatever else the algorithm generates at the same precision, so an explicit dtype is not confined to the points. Transforming a mesh with transform() and transform_all_input_vectors=True under 'float64' gives the transformed vector arrays float64 as well, doubling their memory. Arrays the filter does not transform keep the dtype they had.

Added in version 0.49.

Examples

Download Python source code | Download Jupyter notebook

By default a filter produces whatever VTK produces, and vtkShrinkFilter produces single precision.

>>> import pyvista as pv
>>> from pyvista import examples
>>> mesh = examples.cells.Hexahedron()
>>> mesh.points.dtype
dtype('float64')
>>> mesh.shrink(1.0).points.dtype
dtype('float32')

Ask for the dtype to survive the filter instead. It does, and because this filter cannot compute in double, the widened points are reported as holding single-precision values.

>>> import warnings
>>> pv.global_config.points_dtype = 'preserve'
>>> with warnings.catch_warnings(record=True) as caught:
...     warnings.simplefilter('always')
...     shrunk = mesh.shrink(1.0)
>>> shrunk.points.dtype
dtype('float64')
>>> print(caught[0].message)
vtkShrinkFilter generated float32 points, and cannot generate the float64...
The output points are cast to float64, but hold float32 values.

Treat that as an error instead wherever the fabricated precision is not acceptable. This is a standard warnings filter, so it can be scoped to a block, a module, or a whole session, and set from -W or pytest as well.

>>> with warnings.catch_warnings():
...     warnings.filterwarnings('error', category=pv.PrecisionWarning)
...     try:
...         _ = mesh.shrink(1.0)
...     except pv.PrecisionWarning as error:
...         print(f'raised: {type(error).__name__}')
raised: PrecisionWarning

Sources follow the setting too.

>>> pv.global_config.points_dtype = 'float64'
>>> pv.Sphere().points.dtype
dtype('float64')

>>> pv.global_config.points_dtype = None  # restore default

property show_vtk_api: bool

Return or set whether VTK-inherited attributes appear in dir().

When False (the default), attributes inherited from VTK base classes are hidden from dir() and tab-completion on PyVista objects that wrap VTK types (data objects, Renderer, Actor, Property, etc.). This keeps the public surface curated for data-science IDEs such as Positron’s Variables pane and VS Code’s Jupyter extension, and for IPython / Jupyter tab-completion. VTK methods remain fully callable regardless of this setting.

When True, the full VTK API is enumerated alongside the PyVista API, which is useful for VTK developers who want to discover the raw VTK method surface via introspection.

Warning

This option requires runtime inspection and does not work with all developer tools, for example, it has no effect when using PyCharm. This is because it relies on calling the object’s __dir__ method for generating auto-completion suggestions. Tools like PyCharm that only use static analysis for auto-completion are therefore unaffected.

Notes

The snake_case VTK aliases (number_of_points, deep_copy, and so on) are controlled separately by pyvista.vtk_snake_case(). When snake_case is not 'allow' (the default), those names are hidden from dir() regardless of this setting, because accessing them would already raise PyVistaAttributeError. Enabling snake_case surfaces the snake_case names in dir(); show_vtk_api only controls the CamelCase VTK API.

Added in version 0.48.

Examples

Download Python source code | Download Jupyter notebook

>>> import pyvista as pv
>>> pv.global_config.show_vtk_api
False
>>> pv.global_config.show_vtk_api = True
>>> pv.global_config.show_vtk_api = False  # restore default

property validate_on_wrap: bool

Return or set whether pyvista.wrap() validates data arrays.

When True (the default), pyvista.wrap() performs a cheap array-length sanity check on every VTK object it wraps and emits a InvalidMeshWarning if any point or cell data array has a tuple count that does not match the dataset’s point or cell count. Set to False to skip this check globally when the cost matters in tight loops and the caller trusts their inputs.

Notes

Per-call control is also available via the validate keyword on pyvista.wrap(), pyvista.read(), and pyvista.BaseReader.read(). The per-call keyword takes precedence; this global setting is consulted only when the per-call keyword is left at its default None.

Added in version 0.48.

Examples

Download Python source code | Download Jupyter notebook

>>> import pyvista as pv
>>> pv.global_config.validate_on_wrap
True
>>> pv.global_config.validate_on_wrap = False
>>> pv.global_config.validate_on_wrap = True  # restore default

The warning emitted when validate_on_wrap finds an invalid data array:

class InvalidMeshWarning

Warning for invalid mesh properties.

Added in version 0.47.

The warning emitted when points_dtype asks an algorithm for double-precision points it cannot generate, so the output is cast up and the dtype ends up wider than the values behind it:

class PrecisionWarning

Warning that points could not be generated at the requested precision.

Raised when pyvista.core.config.Config.points_dtype asks for a wider dtype than the VTK algorithm that ran can generate. The output points are cast up so that the dtype is the one asked for, but the values they hold have the precision the algorithm produced, and casting cannot bring back digits it already discarded.

The message names whatever generated the points: the VTK class for a filter, the PyVista class for a source, since a source is its own algorithm, and the library for a hull computed outside VTK.

Being a warning rather than an error is what keeps the choice with the caller. Escalate it where the fabricated precision is not acceptable:

warnings.filterwarnings('error', category=pv.PrecisionWarning)

or silence it where it is:

warnings.filterwarnings('ignore', category=pv.PrecisionWarning)

Either can be scoped to a block with warnings.catch_warnings, or set for a run from -W or a test runner’s own configuration.

Added in version 0.49.

Module-Level Flags

These attributes are plain module globals. Set them at runtime to change the behavior of the whole process:

import pyvista as pv

pv.OFF_SCREEN = True

pv.OFF_SCREEN (default: False)

Render all plots off screen, without opening a window. Initialized from PYVISTA_OFF_SCREEN.

pv.BUILDING_GALLERY (default: False)

Enable behavior needed when Sphinx-Gallery builds the example gallery. Initialized from PYVISTA_BUILDING_GALLERY.

pv.FIGURE_PATH (default: None)

Directory where screenshots are saved when a relative file name is given. Initialized from PYVISTA_FIGURE_PATH.

pv.ON_SCREENSHOT (default: False)

Render off screen and save a screenshot with a unique file name each time a plot is shown. Initialized from PYVISTA_ON_SCREENSHOT.

pv.PLOT_DIRECTIVE_THEME (default: None)

Theme applied by the pyvista-plot Sphinx directive when building documentation.

pv.FLOAT_FORMAT (default: '{:.3e}')

Format string used to print floats in dataset representations.

pv.PICKLE_FORMAT (default: 'vtk')

In-memory serialization format used when pickling a DataObject. Set it with pyvista.set_pickle_format().

pv.DEFAULT_SCALARS_NAME (default: 'Data')

Name given to data arrays added without a name.

pv.MAX_N_COLOR_BARS (default: 10)

Maximum number of color bars a plotter can show at once.

Environment Variables

Most environment variables are read once, when PyVista (or the module that uses them) is first imported. The theme-related variables are re-read each time a new Theme is created. Use the runtime equivalent listed with each variable to change behavior in a running process. Boolean variables accept true or false (case-insensitive).

Rendering

PYVISTA_OFF_SCREEN

Render all plots off screen, without opening a window. Sets pv.OFF_SCREEN; a single plotter can opt in with pv.Plotter(off_screen=True).

PYVISTA_MULTI_SAMPLES

Number of multi-samples used for anti-aliasing. Sets the default of pyvista.plotting.themes.Theme.multi_samples.

PYVISTA_AUTO_CLOSE

Set to false to stop plotters from closing automatically after showing. Sets the default of pyvista.plotting.themes.Theme.auto_close.

Note

• VTK’s own VTK_DEFAULT_OPENGL_WINDOW environment variable selects the render window class VTK creates, such as an EGL window for headless rendering; see the VTK runtime settings.

• PYVISTA_VIRTUAL_DISPLAY, asked about in issue #8120, is not a PyVista setting.

• interactive controls whether shown plots accept user interaction, not off-screen rendering.

Theme and Jupyter

PYVISTA_PLOT_THEME

Theme to apply when the plotting module is first loaded. Any name reported by pyvista.registered_themes() is accepted, as is a "package.module:ClassName" dotted path to a Theme subclass. An invalid value emits a warning. Equivalent to calling pyvista.set_plot_theme().

PYVISTA_JUPYTER_BACKEND

Default Jupyter plotting backend. Sets the default of pyvista.plotting.themes.Theme.jupyter_backend. See Jupyter Notebook Plotting.

PYVISTA_TRAME_SERVER_PROXY_PREFIX

URL prefix for a Jupyter server proxy. Setting it also enables the proxy. See Trame Jupyter Backend for PyVista.

PYVISTA_TRAME_JUPYTER_MODE

How Trame communicates with Jupyter: extension, proxy, or native. See Trame Jupyter Backend for PyVista.

VTK

PYVISTA_VTK_BACKEND

Which VTK build PyVista imports: vtk or vtkmodules for stock VTK, or the package name of an alternative build. Query the active backend with pyvista.vtk_backend().

Example Data

PYVISTA_USERDATA_PATH

Writable directory where downloaded example data is cached. See Examples & Datasets.

PYVISTA_DATA

Path to a local clone of pyvista/data to use instead of downloading example files. See Examples & Datasets.

Changed in version 0.49: Renamed from PYVISTA_VTK_DATA. The old name is deprecated but still accepted when the new name is not set.

The settings derived from both variables appear in the output of pv.Report(downloads=True).

Documentation Building

PYVISTA_FIGURE_PATH

Directory where screenshots are saved when a relative file name is given. Sets pv.FIGURE_PATH.

PYVISTA_BUILDING_GALLERY

Enable Sphinx-Gallery build behavior. Sets pv.BUILDING_GALLERY.

PYVISTA_ON_SCREENSHOT

Save a screenshot each time a plot is shown. Sets pv.ON_SCREENSHOT.

Note

PYVISTA_GALLERY_FORCE_STATIC and PYVISTA_GALLERY_FORCE_STATIC_IN_DOCUMENT are not environment variables: they are Python variables assigned inside a Sphinx-Gallery example script to force static images for one plot or for a whole document.

Note

PYVISTA_KILL_DISPLAY is no longer used and has no effect.

VTK Interface Controls

These settings control how PyVista interacts with VTK at runtime. The state managers pv.vtk_verbosity, pv.vtk_snake_case, and pv.allow_new_attributes, along with pyvista.enable_smp_tools(), apply globally when called and temporarily when used as context managers:

import pyvista as pv

pv.vtk_verbosity('off')  # applies globally

with pv.vtk_verbosity('info'):  # applies within the context
    ...

vtk_verbosity	Context manager to set VTK verbosity level.
vtk_snake_case	Context manager to control access to VTK's pythonic snake_case API.
allow_new_attributes	Context manager to control setting new attributes on PyVista classes.
enable_smp_tools([backend, n_threads])	Enable a VTK SMP backend for filters that support shared-memory parallelism.
vtk_backend()	Return the name of the VTK build PyVista is running against.

Related settings: show_vtk_api on pv.global_config controls whether the VTK-inherited API appears in dir() and tab completion, and pv.vtk_version_info reports the version of VTK in use.

See also

Transitioning From VTK to PyVista

How PyVista’s interface relates to VTK’s.

Extension Registries

Third-party packages extend PyVista through registries. Each registry has a function for registering at runtime and an entry-point group for registering from a package’s pyproject.toml so the extension is discovered without an explicit import.

Extension	Register	List	Entry-point group
File readers	register_reader()	registered_readers()	pyvista.readers
File writers	register_writer()	registered_writers()	pyvista.writers
Dataset accessors	register_dataset_accessor()	registered_accessors()	pyvista.accessors
Plotter components	register_plotter_component()	registered_plotter_components()	pyvista.plotter_components
Jupyter backends	register_jupyter_backend()	registered_jupyter_backends()	pyvista.jupyter_backends
Themes	Subclass Theme	registered_themes()	pyvista.themes
Interactor styles	register_interactor_style()		pyvista.interactor_styles

See also

Extending PyVista

Guide to writing a plugin package, with a worked accessor example.

Inspecting the Environment

pyvista.Report summarizes the running environment: package versions, GPU information, and, with pv.Report(downloads=True), the example-data configuration.