Readers

PyVista provides class based readers to have more control over reading data files. These classes allows for more fine-grained control over reading datasets from files. See pyvista.get_reader() for a list of file types supported.

Also, see Load data using a Reader for a full example using reader classes.

get_reader(filename[, force_ext])

Get a reader for fine-grained control of reading data files.

Reader Classes

AVSucdReader(*args, **kwargs)	AVSucdReader for .inp files.
BMPReader(*args, **kwargs)	BMP Reader for .bmp files.
BYUReader(*args, **kwargs)	BYU Reader for .g files.
BinaryMarchingCubesReader(*args, **kwargs)	BinaryMarchingCubes Reader for .tri files.
CGNSReader(*args, **kwargs)	CGNS Reader for .cgns files.
DEMReader(*args, **kwargs)	DEM Reader for .dem files.
DICOMReader(*args, **kwargs)	DICOM Reader for reading .dcm files.
EnSightReader(*args, **kwargs)	EnSight Reader for .case files.
ExodusIIBlockSet(*args, **kwargs)	Class for enabling and disabling blocks, sets, and block/set arrays in Exodus II files.
ExodusIIReader(*args, **kwargs)	ExodusIIReader for .e and .exo files.
FacetReader(*args, **kwargs)	Facet Reader for .facet files.
FLUENTCFFReader(*args, **kwargs)	FLUENTCFFReader for .h5 files.
FluentReader(*args, **kwargs)	FluentReader for .cas files.
FRDReader(*args, **kwargs)	Reader for CalculiX FRD ASCII result files (.frd).
GambitReader(*args, **kwargs)	GambitReader for .neu files.
GaussianCubeReader(*args, **kwargs)	GaussianCubeReader for .cube files.
GESignaReader(*args, **kwargs)	GESignaReader for .MR files.
GIFReader(*args, **kwargs)	GIFReader for .gif files.
GLTFReader(*args, **kwargs)	GLTFeader for .gltf and .glb files.
HDFReader(*args, **kwargs)	HDFReader for .hdf files.
HDRReader(*args, **kwargs)	HDRReader for .hdr files.
JPEGReader(*args, **kwargs)	JPEG Reader for .jpeg and .jpg files.
MFIXReader(*args, **kwargs)	MFIXReader for .res files.
MetaImageReader(*args, **kwargs)	Meta Image Reader for .mha and .mhd files.
MINCImageReader(*args, **kwargs)	MINCImageReader for .mnc files.
MultiBlockPlot3DReader(*args, **kwargs)	MultiBlock Plot3D Reader.
Nek5000Reader(*args, **kwargs)	Class for reading .nek5000 files produced by Nek5000 and NekRS.
NIFTIReader(*args, **kwargs)	NIFTI Reader for .nii and .nii.gz files.
NRRDReader(*args, **kwargs)	NRRDReader for .nrrd and .nhdr files.
OBJReader(*args, **kwargs)	OBJ Reader for reading .obj files.
OpenFOAMReader(*args, **kwargs)	OpenFOAM Reader for .foam files.
ParticleReader(*args, **kwargs)	ParticleReader for .raw files.
PDBReader(*args, **kwargs)	PDBReader for .pdb files.
PLYReader(*args, **kwargs)	PLY Reader for reading .ply files.
PNGReader(*args, **kwargs)	PNGReader for .png files.
PNMReader(*args, **kwargs)	PNMReader for .pnm files.
POpenFOAMReader(*args, **kwargs)	Parallel OpenFOAM Reader for .foam files.
PTSReader(*args, **kwargs)	PTSReader for .pts files.
PVDReader(*args, **kwargs)	PVD Reader for .pvd files.
Plot3DMetaReader(*args, **kwargs)	Plot3DMeta Reader for .p3d files.
ProStarReader(*args, **kwargs)	ProStarReader for .vrt files.
SLCReader(*args, **kwargs)	SLCReader for .slc files.
STLReader(*args, **kwargs)	STL Reader for .stl files.
SegYReader(*args, **kwargs)	SegYReader for .sgy and .segy files.
SeriesReader(*args, **kwargs)	Class for reading .series file supported by Paraview.
TIFFReader(*args, **kwargs)	TIFFReader for .tif and .tiff files.
TecplotReader(*args, **kwargs)	Tecplot Reader for ascii .dat files.
VTKDataSetReader(*args, **kwargs)	VTK Data Set Reader for .vtk files.
VTKPDataSetReader(*args, **kwargs)	Parallel VTK Data Set Reader for .pvtk files.
XMLImageDataReader(*args, **kwargs)	XML Image Data Reader for .vti files.
XMLMultiBlockDataReader(*args, **kwargs)	XML MultiBlock Data Reader for .vtm or .vtmb files.
XMLPImageDataReader(*args, **kwargs)	Parallel XML Image Data Reader for .pvti files.
XMLPRectilinearGridReader(*args, **kwargs)	Parallel XML RectilinearGrid Reader for .pvtr files.
XMLPUnstructuredGridReader(*args, **kwargs)	Parallel XML UnstructuredGrid Reader for .pvtu files.
XMLPartitionedDataSetReader(*args, **kwargs)	XML PartitionedDataSet Reader for reading .vtpd files.
XMLPolyDataReader(*args, **kwargs)	XML PolyData Reader for .vtp files.
XMLRectilinearGridReader(*args, **kwargs)	XML RectilinearGrid Reader for .vtr files.
XMLStructuredGridReader(*args, **kwargs)	XML StructuredGrid Reader for .vts files.
XMLUnstructuredGridReader(*args, **kwargs)	XML UnstructuredGrid Reader for .vtu files.
XdmfReader(*args, **kwargs)	XdmfReader for .xdmf files.

Custom Readers

Third-party packages can register custom readers so that pyvista.read() handles additional file formats automatically. Registration can be done programmatically or via Python entry points for zero-config discovery at install time.

register_reader(

key: str,

handler: ReaderHandler | None = None,

*,

override: bool = False,

) → Callable[[ReaderHandler], ReaderHandler] | None

Register a custom reader for a file extension.

Can be used as a plain call or as a decorator.

Added in version 0.48.0.

Parameters:

keystr

A file extension (e.g. '.myformat').

handlercallable(), optional

A callable with signature handler(path: str, **kwargs) that returns a pyvista.DataSet. When omitted the function acts as a decorator and returns the decorated callable unchanged.

overridebool, default: False

If True, allow overriding a built-in VTK reader for this extension and silence the warning that would otherwise fire when replacing an existing custom registration.

Returns:

callable() or None

When used as a decorator (handler omitted), returns the decorated function. Otherwise returns None.

Raises:

ValueError

If key collides with a built-in VTK reader and override is False.

Warns:

UserWarning

If key already refers to a registered custom reader. The new registration replaces the old one (last wins); pass override=True to silence the warning.

See also

pyvista.register_writer

Sibling API for registering custom writers.

pyvista.registered_readers

Introspect every registered reader.

Examples

Register a reader for a custom file extension.

>>> import pyvista as pv
>>> def my_reader(path, **kwargs): ...
>>> pv.register_reader('.myformat', my_reader)

Use as a decorator.

>>> @pv.register_reader('.myformat')
... def my_reader(path, **kwargs): ...

registered_readers() → tuple[ReaderRegistration, ...]

Return every custom reader currently registered.

Forces discovery of any pending entry-point plugins so the returned list reflects every reader visible to PyVista. A plugin that fails to import emits a UserWarning and is skipped; the rest still appear in the result.

Added in version 0.48.0.

Returns:

tuple[ReaderRegistration, …]

One record per registered extension. Each record exposes extension, handler, and source.

Examples

>>> import pyvista as pv
>>> def my_reader(path, **kwargs): ...
>>> pv.register_reader('.demo_reader', my_reader)
>>> [
...     r.extension
...     for r in pv.registered_readers()
...     if r.extension == '.demo_reader'
... ]
['.demo_reader']

class ReaderRegistration(extension: str, handler: ReaderHandler, source: str)

Describe one registered custom reader.

Returned by registered_readers().

Added in version 0.48.0.

Attributes:

extensionstr

File extension the reader is registered against, including the leading dot (e.g. '.myformat').

handlercallable()

The reader callable.

sourcestr

Human-readable origin in the form 'module.qualname' for explicit registrations or the entry-point value for plugin-discovered registrations.

Entry points

Packages can also register readers in pyproject.toml so they are discovered automatically when installed:

[project.entry-points."pyvista.readers"]
".myformat" = "my_package:read_my_format"

Remote URI support

When pyvista.read() is given a remote URI (https://, s3://, etc.) and a custom reader is registered for the file extension, the URI is passed directly to the reader. If the reader raises LocalFileRequiredError, PyVista downloads the file to a temporary local path and retries. For built-in formats with no custom reader, the download happens automatically. This uses fsspec when available (install with pip install pyvista[io]), falling back to pooch for HTTP(S) URIs.

class LocalFileRequiredError

Raise from a registered reader to signal it needs a local file path.

When pyvista.read() passes a remote URI to a custom reader and the reader raises this exception, PyVista will download the file to a temporary local path and retry the reader automatically.

Examples

>>> import pyvista as pv
>>> from pyvista.core.utilities.reader_registry import LocalFileRequiredError
>>> @pv.register_reader('.myformat')
... def my_reader(path, **kwargs):
...     if '://' in path:
...         raise LocalFileRequiredError
...     ...

has_scheme(value: str) → bool

Return True if value starts with a URI scheme (e.g. https://).

Parameters:

valuestr

The string to check.

Returns:

bool

True if value contains a :// scheme prefix before the first /.

Custom Writers

Third-party packages can register custom writers so that pyvista.DataObject.save() handles additional file formats automatically. Registration mirrors pyvista.register_reader() and supports programmatic calls, decorators, and Python entry points for zero-config discovery at install time.

register_writer(

key: str,

handler: WriterHandler | None = None,

*,

override: bool = False,

) → Callable[[WriterHandler], WriterHandler] | None

Register a custom writer for a file extension.

Can be used as a plain call or as a decorator.

Added in version 0.48.0.

Parameters:

keystr

A file extension (e.g. '.myformat').

handlercallable(), optional

A callable with signature handler(dataset, path, **kwargs) that writes dataset to path. Any extra keyword arguments passed to pyvista.DataObject.save() are forwarded to the handler as **kwargs — use them to expose format-specific options such as compression level, thread count, or chunking. Handlers that do not need per-call options can omit **kwargs; a call to save() that passes extras to such a handler will raise TypeError from Python itself. When handler is omitted the function acts as a decorator and returns the decorated callable unchanged.

overridebool, default: False

If True, allow overriding a built-in PyVista writer for this extension and silence the warning that would otherwise fire when replacing an existing custom registration.

Returns:

callable() or None

When used as a decorator (handler omitted), returns the decorated function. Otherwise returns None.

Raises:

ValueError

If key collides with a built-in PyVista writer and override is False.

Warns:

UserWarning

If key already refers to a registered custom writer. The new registration replaces the old one (last wins); pass override=True to silence the warning.

See also

pyvista.register_reader

Sibling API for registering custom readers.

pyvista.registered_writers

Introspect every registered writer.

Notes

When pyvista.DataObject.save() is called, registered custom writers are dispatched before built-in VTK writers — mirroring the dispatch order of pyvista.read(). Passing override=True is therefore the only way to replace a built-in writer at save time.

Any keyword arguments passed to save() beyond its documented parameters are forwarded verbatim to the registered handler. When no custom writer is registered for the target extension, extra keyword arguments raise TypeError from save() — PyVista never silently drops writer options.

Examples

Register a writer for a custom file extension with a format-specific option.

>>> import pyvista as pv
>>> def my_writer(dataset, path, *, level=3): ...
>>> pv.register_writer('.myformat', my_writer)
>>> pv.Sphere().save('sphere.myformat', level=9)

Use as a decorator.

>>> @pv.register_writer('.myformat')
... def my_writer(dataset, path, **kwargs): ...

registered_writers() → tuple[WriterRegistration, ...]

Return every custom writer currently registered.

Forces discovery of any pending entry-point plugins so the returned list reflects every writer visible to PyVista. A plugin that fails to import emits a UserWarning and is skipped; the rest still appear in the result.

Added in version 0.48.0.

Returns:

tuple[WriterRegistration, …]

One record per registered extension. Each record exposes extension, handler, and source.

Examples

>>> import pyvista as pv
>>> def my_writer(dataset, path, **kwargs): ...
>>> pv.register_writer('.demo_writer', my_writer)
>>> [
...     r.extension
...     for r in pv.registered_writers()
...     if r.extension == '.demo_writer'
... ]
['.demo_writer']

class WriterRegistration(extension: str, handler: WriterHandler, source: str)

Describe one registered custom writer.

Returned by registered_writers().

Added in version 0.48.0.

Attributes:

extensionstr

File extension the writer is registered against, including the leading dot (e.g. '.myformat').

handlercallable()

The writer callable.

sourcestr

Human-readable origin in the form 'module.qualname' for explicit registrations or the entry-point value for plugin-discovered registrations.

Handler signature

A writer handler is a callable handler(dataset, path, **kwargs) that writes dataset to path. Any extra keyword arguments passed to pyvista.DataObject.save() beyond its documented parameters are forwarded verbatim to the handler as **kwargs. Use them to expose format-specific options such as compression level, thread count, or chunking. When no custom writer is registered for the target extension, passing extra keyword arguments to save() raises TypeError; PyVista never silently drops writer options.

Entry points

Packages can register writers in pyproject.toml so they are discovered automatically when installed:

[project.entry-points."pyvista.writers"]
".myformat" = "my_package:write_my_format"

Dispatch order

When save() is called, custom writers registered via pyvista.register_writer() are dispatched before built-in VTK writers for the same extension, mirroring the dispatch order used by pyvista.read(). By default, registering a handler for an extension that collides with a built-in PyVista writer raises ValueError; pass override=True to replace the built-in writer.

The .pv Format: PyVista’s Native Binary Format

PyVista has a native zstd-compressed binary format with the .pv extension, implemented by the pyvista-zstd companion package. It is a compact, multi-threaded format for fast dataset I/O and is included in the io extra:

pip install pyvista[io]

Once installed, .pv round-trips “just work” via the pyvista.readers and pyvista.writers entry-point hooks without any manual registration:

import pyvista as pv

mesh = pv.Sphere()
mesh.save('sphere.pv')
pv.read('sphere.pv')

Supported dataset types include ImageData, PolyData, StructuredGrid, RectilinearGrid, UnstructuredGrid, MultiBlock, and ExplicitStructuredGrid. The format uses zstd compression with multi-threaded encode/decode and is a good choice over .vtu / .vtp / .vtm when file size or I/O latency matters.

Writer Classes

PyVista provides built-in writer classes for saving datasets to various file formats. These are used internally by pyvista.DataObject.save().

BaseWriter(*args, **kwargs)	The base writer class.
BMPWriter(*args, **kwargs)	BMPWriter for .bmp files.
DataSetWriter(*args, **kwargs)	DataSetWriter for VTK legacy dataset files .vtk.
HDFWriter(*args, **kwargs)	HDFWriter for .hdf and .vtkhdf files.
HoudiniPolyDataWriter(*args, **kwargs)	HoudiniPolyDataWriter for Houdini geometry .geo files.
IVWriter(*args, **kwargs)	IVWriter for OpenInventor .iv files.
JPEGWriter(*args, **kwargs)	JPEGWriter for .jpeg and .jpg files.
NIFTIImageWriter(*args, **kwargs)	NIFTIImageWriter for .nii and .nii.gz files.
OBJWriter(*args, **kwargs)	OBJWriter for Wavefront .obj files.
PLYWriter(*args, **kwargs)	PLYWriter for PLY polygonal .ply files.
PNGWriter(*args, **kwargs)	PNGWriter for .png files.
PNMWriter(*args, **kwargs)	PNMWriter for .pnm files.
PolyDataWriter(*args, **kwargs)	PolyDataWriter for legacy VTK PolyData .vtk files.
RectilinearGridWriter(*args, **kwargs)	RectilinearGridWriter for legacy VTK rectilinear grid .vtk files.
STLWriter(*args, **kwargs)	STLWriter for stereolithography .stl files.
SimplePointsWriter(*args, **kwargs)	SimplePointsWriter for simple point-set .xyz files.
StructuredGridWriter(*args, **kwargs)	StructuredGridWriter for legacy VTK structured grid .vtk files.
TIFFWriter(*args, **kwargs)	TIFFWriter for .tif and .tiff files.
UnstructuredGridWriter(*args, **kwargs)	UnstructuredGridWriter for legacy VTK unstructured grid .vtk files.
XMLImageDataWriter(*args, **kwargs)	XMLImageDataWriter for VTK XML image data .vti files.
XMLMultiBlockDataWriter(*args, **kwargs)	XMLMultiBlockDataWriter for VTK XML multiblock .vtm files.
XMLPartitionedDataSetWriter(*args, **kwargs)	XMLPartitionedDataSetWriter for VTK XML partitioned datasets .vtpd files.
XMLPolyDataWriter(*args, **kwargs)	XMLPolyDataWriter for VTK XML polydata .vtp files.
XMLRectilinearGridWriter(*args, **kwargs)	XMLRectilinearGridWriter for VTK XML rectilinear grid .vtr files.
XMLStructuredGridWriter(*args, **kwargs)	XMLStructuredGridWriter for VTK XML structured grid .vts files.
XMLUnstructuredGridWriter(*args, **kwargs)	XMLUnstructuredGridWriter for VTK XML unstructured grid .vtu files.

Inherited Classes

The pyvista.BaseReader is inherited by all sub-readers. It has the basic functionality of all readers to set filename and read the data.

The PointCellDataSelection is inherited by readers that support inspecting and setting data related to point and cell arrays.

The TimeReader is inherited by readers that support inspecting and setting time or iterations for reading.

BaseReader(*args, **kwargs)	The Base Reader class.
PointCellDataSelection(*args, **kwargs)	Mixin for readers that support data array selections.
PVDDataSet(*args, **kwargs)	Class for storing dataset info from PVD file.
SeriesDataSet(*args, **kwargs)	Class for storing dataset info from series file.
TimeReader()	Abstract class for readers supporting time.

Enumerations

Enumerations are available to simplify inputs to certain readers.

• Reader Enumerations
  • Plot3DFunctionEnum