PyVista Quick Look

Press the space bar on a mesh file in the Finder and turn it with the mouse, the same way macOS already previews .ply and .usdz models.

Selecting flow.vtu and pressing space shows its surface in the Quick Look panel, coloured by the active scalars and free to rotate and zoom.

Install

macOS 12 or newer. Nothing else needs to be installed first.

curl -LsSf https://raw.githubusercontent.com/user27182/pyvista-quicklook/main/scripts/bootstrap.sh | sh

Then select a .vtu, .vtp, or .vtk file in the Finder and press space. Check the result with pvql doctor.

What the installer does

1. Downloads the latest release: the installer scripts, about 1 MB, and the prebuilt app, about 200 KB.
2. Installs uv if it is missing, and a Python 3.12 if uv finds none on the machine.
3. Installs the pvql helper as a uv tool.
4. Creates a private Python environment and installs PyVista 0.49 with its io extras, among them meshio and pyvista-frd-reader, along with cvista and pyvista-cad. This is the step that takes a while: about 400 MB of wheels.
5. Writes the configuration file and loads PyVista once, so the first preview is quick.
6. Copies the app from the download into ~/Applications and registers it with Launch Services and Quick Look. The downloads are removed once everything is installed.
7. Installs the render service as a launch agent. It appears as PyVista Quick Look under Login Items in System Settings.

No system Python and no existing environment is used or changed.

Where things go

Path	What	Size
~/Library/Application Support/PyVistaQuickLook/venv	The PyVista environment	370 MB
~/Library/Application Support/PyVistaQuickLook/config.json	Configuration	4 KB
~/Applications/PyVista Quick Look.app	The app and its Quick Look extension	500 KB
~/Library/Application Support/uv/tools/pyvista-quicklook	The pvql helper	400 KB
~/.local/bin/pvql, ~/.local/bin/pyvista-quicklook	Links to the helper
~/Library/LaunchAgents/io.github.user27182.pvqld.plist	The render service	4 KB
~/Library/Logs/pvqld.log	The service's output	grows slowly
~/Library/Containers/io.github.user27182.PyVistaQuickLook.QuickLook	The extension's sandbox, created by macOS: its log and staged copies	small
~/Library/Caches/PyVistaQuickLook	One built preview per file previewed	grows with use
~/.local/bin/uv, ~/Library/Application Support/uv	uv, and Python 3.12 if uv had to fetch one	45 MB, plus Python
~/.cache/uv	uv's download cache; the environment's files are clones of it, not copies	shared

About 385 MB in total, or 430 MB when uv is installed too. The environment is the bulk of it:

• cvista[all], a VTK fork used in place of stock VTK, 137 MB
• cascadio, pyvista-cad's STEP reader, 69 MB
• matplotlib, 28 MB
• numpy, 25 MB
• ezdxf, pyvista-cad's DXF reader, 20 MB
• PyVista 0.49, meshio, and the remaining dependencies, about 100 MB

pvql cache --clear empties the preview cache. pvql uninstall removes everything above except the configuration file and uv.

From a checkout, ./scripts/install.sh does the same and builds the app from source, which needs the Xcode command line tools (xcode-select --install):

./scripts/install.sh --prefix /Applications                # install for all users
./scripts/install.sh --app /path/to/PyVistaQuickLook.app   # skip the build

Supported files

76 extensions are claimed, so pressing space on any of these files opens this preview. A file that turns out not to be a mesh, such as a .dat holding a table of numbers, is shown as plain text instead, the way Quick Look would have shown it.

Format	Extensions	Format	Extensions
3D Studio Model	.3ds	OpenFOAM Case	.foam
3MF Model	.3mf	ParaView Data Collection	.pvd
AVS UCD Data	.inp	PERMAS Data	.dato, .post
AVS UCD Mesh	.avs	PLOT3D Metadata	.p3d
Binary Marching Cubes Surface	.tri	Point Cloud	.pts
BYU Geometry	.g	ProStar Mesh	.vrt
CalculiX Result	.frd	Protein Data Bank	.pdb
CGNS Data	.cgns	PyVista Zstandard Data	.pv, .zvtk
Digital Elevation Model	.dem	SEG-Y Seismic Data	.segy, .sgy
DXF Drawing	.dxf	SLC Volume	.slc
Eclipse GRDECL Grid	.grdecl	STEP Model	.step, .stp
EnSight Case	.case	Tecplot ASCII Data	.tec
Exodus II Data	.e, .ex2, .exii, .exo	Tecplot Data	.dat
Facet Surface	.facet	TetGen Mesh	.ele, .node
FLAC3D Grid	.f3grid	VRML Model	.vrml, .wrl
Fluent Case	.cas	VTK File Series	.series
GAMBIT Neutral Mesh	.neu	VTK HDF	.vtkhdf
Gaussian Cube	.cube	VTK Image Data	.vti
GE Signa MR Image	.mr	VTK Legacy Data	.vtk
Gmsh Mesh	.msh	VTK MultiBlock	.vtm, .vtmb
Kratos Model Part	.mdpa	VTK Parallel Image Data	.pvti
Medit Mesh	.mesh, .meshb	VTK Parallel Legacy Data	.pvtk
MetaImage Volume	.mha, .mhd	VTK Parallel Rectilinear Grid	.pvtr
MFIX Result	.res	VTK Parallel Unstructured Grid	.pvtu
MINC Volume	.mnc	VTK Partitioned Dataset	.vtpd
Nastran Bulk Data	.bdf, .fem, .nas	VTK PolyData	.vtp
Nek5000 Data	.nek5000	VTK Rectilinear Grid	.vtr
Netgen Mesh	.vol	VTK Structured Grid	.vts
NIfTI Volume	.nii	VTK Unstructured Grid	.vtu
NRRD Volume	.nhdr, .nrrd	XDMF Data	.xdmf
Object File Format Mesh	.off

4 more are claimed through a type macOS declares, since Launch Services sees only the last suffix of a compressed dataset:

• Gzip Archive (org.gnu.gnu-zip-archive): .dato.gz, .nii.gz, .post.gz, .vol.gz

A folder of DICOM slices is claimed the same way, through public.folder.

PyVista can also read these, which are not claimed:

• macOS previews it: .bmp, .dcm, .gif, .glb, .gltf, .hdr, .jpeg, .jpg, .obj, .ply, .png, .pnm, .stl, .tif, .tiff
• disk images own the extension: .img
• camera raw images own the extension: .raw
• XML owns the extension: .xml
• needs an OpenCascade kernel: .brep, .brp, .fcstd, .iges, .igs
• needs ifcopenshell: .ifc
• needs the openscad program: .scad
• a general HDF5 container: .h5, .hdf
• needs h5py: .h5m, .hmf, .med, .xmf
• meshio fails to read it: .su2, .ugrid
• meshio hangs on it: .wkt
• meshio writes it but does not read it: .svg

Claims on the extensions macOS previews itself, such as STL and PLY, or that another kind of file owns, are ignored by macOS, which is why those are not claimed. To claim fewer, or to add one of the others, edit the config and run the install command again, which rebuilds the app with the new claims:

{ "extensions": { "add": [".h5"], "remove": [".dat"] } }

How it works

The app bundle contains a Quick Look extension that declares a uniform type identifier for each claimed extension. When the Finder previews one of those files, the extension hands it to a background render service, which reads it with PyVista, extracts the surface, colours the vertices by the active scalars, and writes a PLY. The extension shows that PLY in a SceneKit view, which is what makes the preview turnable.

Point data is interpolated across each face. Cell data is drawn flat: the cells are split apart first, so each keeps its own colour. Lines are drawn as tubes and point clouds as spheres, sized to the spacing between points. A volume that carries scalars is cut into three slices through its centre; one without is shown as its outer surface. Open surfaces, the slices among them, are written with a second, flipped side, so they are drawn and lit from wherever the camera looks.

Previews are cached under ~/Library/Caches/PyVistaQuickLook, keyed by the file's path, size, and modification time, so editing a file invalidates its preview, and by the version of the converter, so an update rebuilds them rather than serving old ones.

The service loads PyVista and VTK in the background when it starts, which is at login and whenever it is reinstalled, so the first preview does not wait for them. pvql warmup does the same on demand, and "warm_on_start": false turns the automatic pass off.

Surfaces are sent whole up to max_scene_points. Above that, images and volumes are thinned on their lattice and other surfaces are decimated. Set it to 0 to never thin.

A claimed file that turns out not to be a mesh is shown the way Quick Look would have shown it: as plain text when it reads as text, such as a .dat holding a table of numbers, and otherwise as its icon, name, size, and date, with a line saying why it holds no mesh. A problem with the installation itself, such as a render service that is not running, is reported in full instead.

Compressed and multi-file datasets

Two kinds of dataset are not a single file with a claimable extension, and both are reached by claiming the type macOS gives them instead.

A compressed dataset is named .nii.gz or .vol.gz, but Launch Services sees only .gz and keeps its own type for it, so declaring those extensions does nothing. The extension claims the gzip type: press space on a gzipped NIfTI, PERMAS, Netgen, or Medit file and it is drawn like any other. Every other gzip, a tarball or a compressed log, shows its details.

A DICOM series is a folder of slices, so the folder is what gets previewed. Press space on one in the Finder and the slices are read as a single volume, cut through its centre and coloured, the same as any other volume. Folders are claimed for this, so the extension checks whether a folder holds DICOM files before it asks the render service: it looks for the DICM marker in the first few entries, whatever they are named, and an ordinary folder shows its own details immediately, as the Finder would.

Still images

With "interactive": false in the config, every preview is a still image rendered by pyvista plot --off-screen --screenshot instead, which keeps the scalar bar and axes the interactive view leaves out.

The render service

macOS runs Quick Look extensions in a sandbox that VTK cannot run inside, so reading and conversion happen in a launch agent instead. The installer sets it up.

pvql service            # report whether it is loaded
pvql service --install  # (re)install and start it
pvql service --uninstall

It appears as PyVista Quick Look under Login Items in System Settings, and its output goes to ~/Library/Logs/pvqld.log. macOS names it pyvista-quicklook when it asks whether to let it read a folder, since that is the program the service runs as.

Files in the Desktop, Documents, and Downloads folders

macOS keeps those folders private to each program, and the render service cannot read them. The Quick Look extension copies the file it was asked to preview into its own container so that the service can convert it anyway.

A dataset that points at neighbouring files — .pvd, .vtm, .case, .foam — needs those neighbours, which the copy does not include. Keep such datasets outside those three folders, or grant the render service Full Disk Access in System Settings under Privacy & Security.

Configuration

~/Library/Application Support/PyVistaQuickLook/config.json

Key	Default	Effect
python	set at install	Interpreter of the PyVista environment
pvql	discovered	Absolute path to the pvql helper
interactive	true	Show a turnable surface; false renders a still image instead
max_scene_points	2000000	Thin surfaces above this many points; 0 never does
max_glyph_points	20000	Draw at most this many points of a point cloud; 0 draws all
max_file_size_mb	512	Files above this size show a notice instead of a preview, and are never copied
timeout	60	Seconds before a conversion is abandoned
warm_on_start	true	Load PyVista and VTK when the render service starts
window_size	[1024, 1024]	Still image size in pixels
background	null	Background colour passed to pyvista plot
extra_args	[]	Extra arguments appended to pyvista plot
cache	true	Reuse previously built previews
log	false	Append activity to pvql.log beside the config file

Changing extensions requires a reinstall, because the claimed types are baked into the app bundle. Every other key takes effect on the next preview.

Commands

pvql preview FILE     # build a preview and print its cached path
pvql warm DIR         # build previews for a directory ahead of time
pvql warmup           # load PyVista and VTK ahead of the first preview
pvql types            # list claimed extensions
pvql doctor           # check every part of the integration
pvql service          # manage the render service
pvql config --init    # write a config file with discovered defaults
pvql cache --clear    # delete cached previews
pvql uninstall        # remove everything, asking first

Troubleshooting

Run pvql doctor first; it checks the helper, the app, the extension registration, the service, and a real preview.

• The panel says the service is not answering. Run pvql service --install.
• Nothing happens on space bar. Confirm the type is claimed with pvql types, then check that Finder resolves it: mdls -name kMDItemContentType yourfile.vtu should report an io.github.user27182.pyvista-quicklook.* type.
• Previews are stale. pvql cache --clear.
• A preview fails. Set "log": true in the config; activity is appended to pvql.log beside it. The extension's own log is in ~/Library/Containers/io.github.user27182.PyVistaQuickLook.QuickLook/Data/tmp/.

Development

uv sync --group dev
uv run pytest tests/          # helper and exporter tests, with coverage
uv run pre-commit run --all-files
./scripts/build.sh            # compile and sign the app bundle

Everything runs on one Python, 3.14: the tests, the pvql helper in its uv tool environment, and the PyVista environment beside it. [tool.uv] in pyproject.toml overrides PyVista's stock VTK requirement so the test environment holds the same packages the installer provisions.

PyVista and cvista are pinned to one release each, in pyproject.toml and scripts/install.sh alike. Bumping either reruns a test that compares every extension the environment can read with the format table, so a reader that PyVista adds, drops, or moves to a package of its own shows up as a failure to resolve in formats.py. The README's format tables are generated from PyVista's reader tables and checked by another test:

uv run python -m pyvista_quicklook._formats_table README.md

One project, three names, each where its own conventions apply: pyvista-quicklook is the package on PyPI and the program the render service runs as, pvql is the command, and PyVista Quick Look is what the reader sees, from the app bundle to the panel. The build's own files keep the compact PyVistaQuickLook spelling: the bundle identifier, the executables, and the downloadable zip.

main is protected by a pre-commit hook, so work on a branch.

Releases are published by CI: push a v* tag and the publish job uploads the helper to PyPI through trusted publishing from the release environment, while the release job attaches the built app to the tag's GitHub release, which is what the installer downloads.

Uninstall

pvql uninstall

It lists what it is about to remove and asks first: the app, the render service, the PyVista environment, the cache, and the pvql command itself. The configuration file is kept unless you pass --all, and uv is left in place, with a note on how to remove that too if the installer is what put it there. The app's own window has an Uninstall button that does the same.