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).

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 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.

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.