read

read(

filename: PathStrSeq,

force_ext: str | None = None,

file_format: str | None = None,

progress_bar: bool = False,

*,

cls: type[DataObject] | None = None,

validate: bool | None = None,

**kwargs,

) → DataObject

Read any file type supported by vtk or meshio.

Automatically determines the correct reader to use then wraps the corresponding mesh as a pyvista object. Attempts native vtk readers first then tries to use meshio.

Remote URIs (https://, s3://, etc.) are downloaded to a temporary file automatically. Install fsspec for full protocol support (pip install pyvista[io]); pooch is used as a fallback for HTTP(S). Third-party reader plugins registered via pyvista.register_reader() are also checked.

See pyvista.get_reader() for list of vtk formats supported.

Tip

A native .pv binary format with zstd compression is available via the pyvista-zstd companion package, included in the io extra (pip install pyvista[io]). It is a compact, multi-threaded alternative to the built-in VTK formats below when file size or I/O latency matters. Third-party packages can register additional custom writers via pyvista.register_writer().

ImageData File Formats

File Format	File Extension(s)	read()	save()
BMP	.bmp
DEM	.dem
DICOM	.dcm, .img
GESigna	.mr
GIF	.gif
GaussianCube	.cube
HDF	.hdf, .vtkhdf
HDR	.hdr
JPEG	.jpeg, .jpg
MINC	.mnc
Meta	.mha, .mhd
NIFTI	.nii, .nii.gz
NRRD	.nhdr, .nrrd
PNG	.png
PNM	.pnm
SLC	.slc
SegY	.segy, .sgy
Series	.series
TIFF	.tif, .tiff
VTK	.vtk
VTKP	.pvtk
XML	.vti
XMLP	.pvti

RectilinearGrid File Formats

File Format	File Extension(s)	read()	save()
Series	.series
VTK	.vtk
VTKP	.pvtk
XML	.vtr
XMLP	.pvtr
Xdmf	.xdmf

StructuredGrid File Formats

File Format	File Extension(s)	read()	save()
SegY	.segy, .sgy
Series	.series
VTK	.vtk
VTKP	.pvtk
XML	.vts
Xdmf	.xdmf

PolyData File Formats

File Format	File Extension(s)	read()	save()
BYU	.g
BinaryMarchingCubes	.tri
Facet	.facet
GaussianCube	.cube
HDF	.hdf, .vtkhdf
Houdini	.geo
IV	.iv
OBJ	.obj
PDB	.pdb
PLY	.ply
PTS	.pts
Particle	.raw
STL	.stl
Series	.series
VTK	.vtk
VTKP	.pvtk
XML	.vtp

UnstructuredGrid File Formats

File Format	File Extension(s)	read()	save()
AVSucd	.inp
FRD	.frd
Fluent	.cas
Gambit	.neu
HDF	.hdf, .vtkhdf
MFIX	.res
Nek5000	.nek5000
ProStar	.vrt
Series	.series
VTK	.vtk
VTKP	.pvtk
XML	.vtu
XMLP	.pvtu
Xdmf	.xdmf

ExplicitStructuredGrid File Formats

File Format	File Extension(s)	read()	save()
GRDECL	.grdecl
Series	.series
VTK	.vtk
XML	.vtu

MultiBlock File Formats

File Format	File Extension(s)	read()	save()
3DS	.3ds
CGNS	.cgns
EnSight	.case
ExodusII	.e, .ex2, .exii, .exo
FLUENTCFF	.h5
GLTF	.glb, .gltf
HDF	.hdf, .vtkhdf
POpenFOAM	.foam
PVD	.pvd
Plot3DMeta	.p3d
Series	.series
Tecplot	.dat
VRML	.vrml, .wrl
XML	.vtm, .vtmb
Xdmf	.xdmf

PartitionedDataSet File Formats

File Format	File Extension(s)	read()	save()
HDF	.hdf, .vtkhdf
Series	.series
XML	.vtpd

Note

See nschloe/meshio for formats supported by meshio. Be sure to install meshio with pip install meshio if you wish to use it.

Warning

.pkl / .pickle files are not supported and will be refused. Pickle is a Python serialization protocol, not a mesh file format, and loading an untrusted pickle is arbitrary code execution (CWE-502). Use a real mesh format (.vtu, .vtp, .vtm, .vtk, .ply, .stl, …) or install pyvista-zstd for the .pv single-blob format.

Parameters:

filenamestr, Path, Sequence[str | Path]

The string path to the file to read. If a list of files is given, a pyvista.MultiBlock dataset is returned with each file being a separate block in the dataset.

force_extstr, optional

If specified, the reader will be chosen by an extension which is different to its actual extension. For example, '.vts', '.vtu'.

file_formatstr, optional

Format of file to read with meshio.

progress_barbool, default: False

Optionally show a progress bar. Ignored when using meshio.

clstype, optional

Expected concrete type of the returned mesh. When given, the result is checked with isinstance() and a TypeError is raised on mismatch. Static type checkers (mypy, pyright) use this to narrow the return type to cls directly, so callers do not need typing.cast or a manual assert isinstance to access subclass-specific attributes, e.g. pv.read('file.vtu', cls=pv.UnstructuredGrid).

validatebool, optional

Forwarded to pyvista.wrap() as the validate keyword when using a vtk reader. When None (the default), honors pyvista.core.config.Config.validate_on_wrap. Pass False to skip the cheap array-length sanity check on very large trusted files. Has no effect for meshio code paths.

Added in version 0.48.

**kwargsdict, optional

Additional keyword arguments set on the reader after initialization but before reading the file.

This is effectively the same as using get_reader() and setattr.

reader = pyvista.get_reader(file)
for key, value in kwargs.items():
    setattr(reader, key, value)
mesh = reader.read()

Added in version 0.49.

Returns:

pyvista.DataSet | pyvista.MultiBlock

Wrapped PyVista dataset. When cls is given, an instance of cls is returned instead.

See also

pyvista.DataObject.save

Save a mesh to file.

Examples

Load an example mesh.

>>> import pyvista as pv
>>> from pyvista import examples
>>> mesh = pv.read(examples.antfile)
>>> mesh.plot(cpos='xz')

Static Scene

Interactive Scene

Narrow the return type to a specific class. This avoids the need for a manual cast when working with type checkers such as mypy or pyright.

>>> mesh = pv.read('mesh.vtu', cls=pv.UnstructuredGrid)

Load a vtk file.

>>> mesh = pv.read('my_mesh.vtk')

Load a meshio file.

>>> mesh = pv.read('mesh.obj')

Load a .foam file and use keyword arguments to set reader-specific properties such as skip_zero_time.

>>> file = examples.download_openfoam_tubes(load=False)
>>> mesh = pv.read(file, skip_zero_time=True)