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 with its io extras, among them meshio and, from PyVista 0.49, 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

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, from git until 0.49 is released, 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.

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
• the Finder sees .gz: .dato.gz, .nii.gz, .post.gz, .vol.gz
• 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, such as a .dat holding a table of numbers or a .g holding G-code, is shown as plain text, the way Quick Look would have shown it. When a preview fails for another reason, the panel shows the error text.

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.

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

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

.python-version pins the interpreter to 3.12, the last release cvista ships rendering wheels for, and [tool.uv] in pyproject.toml overrides PyVista's stock VTK requirement so the test environment holds the same packages the installer provisions.

PyVista is pinned to one commit, in pyproject.toml and scripts/install.sh alike. Bumping it 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 plugin 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

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; uv is left in place. The app's own window has an Uninstall button that does the same.