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. When False (the default), registering a handler for an extension that collides with a built-in reader raises ValueError.

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.

See also

pyvista.register_writer

Sibling API for registering custom writers.

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

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. When False (the default), registering a handler for an extension that collides with a built-in writer raises ValueError.

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.

See also

pyvista.register_reader

Sibling API for registering custom readers.

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

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.

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.
TimeReader()	Abstract class for readers supporting time.

Enumerations

Enumerations are available to simplify inputs to certain readers.

• Reader Enumerations
  • Plot3DFunctionEnum