pyvista-stl

A fast STL reader for Python. Reads binary and ASCII files, merges duplicate vertices on the way in, and returns NumPy arrays.

On the synthetic 1M-point binary benchmark below, the default single-threaded path reads in about 100 ms on a Ryzen 9 8945HS, roughly 11x faster than VTK and 28x faster than meshio. Opting into the multi-threaded path with threads=0 (auto) reads the same file in 50 ms — about 21x faster than VTK and 55x faster than meshio. The implementation is a memory-mapped parser, an optional multi-threaded ASCII path, and a concurrent open-addressing hashtable for vertex deduplication. See Benchmarks for the numbers and the reproduction script.

The vertex hash function (final96) and the iterative table sizing helper (nextpow2) are taken from aki5/libstl; see src/hash96.h. The rest of the parser is independent.

Installation

pip install pyvista-stl

To build from source:

git clone https://github.com/pyvista/pyvista-stl.git
cd pyvista-stl
pip install .

Usage

Read an STL file as merged (vertices, indices) arrays:

>>> import pyvista_stl
>>> vertices, indices = pyvista_stl.read("example.stl")
>>> vertices
array([[-0.01671113,  0.5450843 , -0.8382146 ],
       [ 0.01671113,  0.5450843 , -0.8382146 ],
       [ 0.        ,  0.52573115, -0.8506509 ],
       ...,
       [ 0.5952229 , -0.57455426,  0.56178033],
       [ 0.56178033, -0.5952229 ,  0.57455426],
       [ 0.57455426, -0.56178033,  0.5952229 ]], dtype=float32)
>>> indices
array([[      0,       1,       2],
       [      1,       3,       4],
       [      4,       5,       2],
       ...,
       [9005998, 9005988, 9005999],
       [9005999, 9005996, 9005995],
       [9005998, 9005999, 9005995]], dtype=int32)

vertices is the deduplicated (n_points, 3) float32 array. indices is the (n_triangles, 3) int32 array of vertex indices into vertices. Both binary and ASCII files are accepted; the format is detected automatically.

By default the reader runs single-threaded, which produces a deterministic vertex ordering. Pass threads=N (an integer >= 2) to opt into the multi-threaded parser, or threads=0 to auto-select hardware_concurrency():

vertices, indices = pyvista_stl.read("example.stl", threads=0)
mesh = pyvista_stl.read_as_mesh("example.stl", threads=8)

To get a pyvista.PolyData directly:

>>> import pyvista_stl
>>> mesh = pyvista_stl.read_as_mesh('example.stl')
>>> mesh
PolyData (0x7f43063ec700)
  N Cells:    1280000
  N Points:   641601
  N Strips:   0
  X Bounds:   -5.000e-01, 5.000e-01
  Y Bounds:   -5.000e-01, 5.000e-01
  Z Bounds:   -5.551e-17, 5.551e-17
  N Arrays:   0

With pyvista >= 0.48 installed, pyvista.read automatically dispatches .stl files to pyvista_stl via the pyvista.readers entry point:

>>> import pyvista as pv
>>> mesh = pv.read("example.stl")  # uses pyvista_stl

Benchmarks

Reading a 1,002,001-point STL (pyvista.Plane(i_resolution=250, j_resolution=250).triangulate().subdivide(2), 2,000,000 triangles), median of 5 runs on a 16-core Ryzen 9 8945HS. The two right-hand columns show how much faster pyvista-stl is than the reader in that row, in single-threaded (threads=1, the default) and multi-threaded (threads=0, all cores) configurations.

Binary STL (~95 MB on disk):

Reader	Time (seconds)	pyvista-stl ST speedup	pyvista-stl MT speedup
pyvista-stl (1 thread)	0.100	(baseline)	2.0x slower
pyvista-stl (16 thr.)	0.051	2.0x faster	(baseline)
numpy-stl	0.206 [1]	2.1x faster	4.0x faster
pyvista (VTK)	1.080	10.8x faster	21.2x faster
meshio	3.041	30.5x faster	59.7x faster

ASCII STL (~425 MB on disk):

Reader	Time (seconds)	pyvista-stl ST speedup	pyvista-stl MT speedup
pyvista-stl (1 thread)	0.388	(baseline)	3.4x slower
pyvista-stl (16 thr.)	0.114	3.4x faster	(baseline)
pyvista (VTK)	2.761	7.1x faster	24.2x faster
meshio	9.464	24.4x faster	83.0x faster

Across the fixture corpus in benchmarks/bench.py (binary and ASCII files from a few KB to roughly 100 MB), single-threaded pyvista-stl is a median of 10.6x faster than VTK, ranging from 4.0x to 134.3x, and is never slower than VTK on any tested file. The multi-threaded path widens the gap further on the larger ASCII files.

Reproduce these numbers with the script in benchmarks/:

python benchmarks/make_readme_figures.py

Comparison with VTK across mesh sizes

The gap widens with file size. pyvista-stl scales near-linearly on both the single-threaded and multi-threaded paths; VTK’s reader scales super-linearly. By the time the mesh reaches ~10 M points (~20 M triangles, ~1 GB binary), pyvista-stl is roughly 65x faster single-threaded and 160x faster multi-threaded:

https://github.com/pyvista/pyvista-stl/raw/main/bench0.png

Same data on log-log axes:

https://github.com/pyvista/pyvista-stl/raw/main/bench1.png

Configuration

The threads keyword argument on read and read_as_mesh controls worker concurrency:

threads=1 (default): single-threaded, deterministic vertex ordering. The safest choice for embedded/server use.
threads=N (N >= 2): use N workers. Worker counts are capped at 32.
threads=0: auto-select using std::thread::hardware_concurrency().

PYVISTA_STL_MAX_TRIS (environment variable, default: 200_000_000) caps the declared triangle count the reader will accept. Files claiming more triangles than the cap raise RuntimeError before any large allocation, which prevents an attacker-controlled header from forcing multi-GB allocations.

License and acknowledgments

This project began as a wrapper around aki5/libstl; the binary-format reader and the hash-based vertex merge are derived from that library, used under its MIT License.

Significant changes since: mmap-backed input, ASCII reader, a multi-threaded path with a concurrent hashtable, hugepage-backed scratch buffers, and a nanobind interface.

This repository is also licensed under the MIT License.

Support

Please open an issue at pyvista/pyvista-stl if you hit a problem.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyvista_stl-0.5.0.tar.gz (27.6 kB view details)

Uploaded Aug 12, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

pyvista_stl-0.5.0-cp314-cp314-win_amd64.whl (256.0 kB view details)

Uploaded Aug 12, 2026 CPython 3.14Windows x86-64

pyvista_stl-0.5.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (67.5 kB view details)

Uploaded Aug 12, 2026 CPython 3.14manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

pyvista_stl-0.5.0-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (63.9 kB view details)

Uploaded Aug 12, 2026 CPython 3.14manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

pyvista_stl-0.5.0-cp314-cp314-macosx_11_0_arm64.whl (56.5 kB view details)

Uploaded Aug 12, 2026 CPython 3.14macOS 11.0+ ARM64

pyvista_stl-0.5.0-cp314-cp314-macosx_10_15_x86_64.whl (59.1 kB view details)

Uploaded Aug 12, 2026 CPython 3.14macOS 10.15+ x86-64

pyvista_stl-0.5.0-cp313-cp313-win_amd64.whl (247.9 kB view details)

Uploaded Aug 12, 2026 CPython 3.13Windows x86-64

pyvista_stl-0.5.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (67.5 kB view details)

Uploaded Aug 12, 2026 CPython 3.13manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

pyvista_stl-0.5.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (63.9 kB view details)

Uploaded Aug 12, 2026 CPython 3.13manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

pyvista_stl-0.5.0-cp313-cp313-macosx_11_0_arm64.whl (56.5 kB view details)

Uploaded Aug 12, 2026 CPython 3.13macOS 11.0+ ARM64

pyvista_stl-0.5.0-cp313-cp313-macosx_10_14_x86_64.whl (59.0 kB view details)

Uploaded Aug 12, 2026 CPython 3.13macOS 10.14+ x86-64

pyvista_stl-0.5.0-cp312-cp312-win_amd64.whl (247.9 kB view details)

Uploaded Aug 12, 2026 CPython 3.12Windows x86-64

pyvista_stl-0.5.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (67.5 kB view details)

Uploaded Aug 12, 2026 CPython 3.12manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

pyvista_stl-0.5.0-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (63.9 kB view details)

Uploaded Aug 12, 2026 CPython 3.12manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

pyvista_stl-0.5.0-cp312-cp312-macosx_11_0_arm64.whl (56.5 kB view details)

Uploaded Aug 12, 2026 CPython 3.12macOS 11.0+ ARM64

pyvista_stl-0.5.0-cp312-cp312-macosx_10_14_x86_64.whl (59.0 kB view details)

Uploaded Aug 12, 2026 CPython 3.12macOS 10.14+ x86-64

pyvista_stl-0.5.0-cp311-cp311-win_amd64.whl (249.8 kB view details)

Uploaded Aug 12, 2026 CPython 3.11Windows x86-64

pyvista_stl-0.5.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (71.5 kB view details)

Uploaded Aug 12, 2026 CPython 3.11manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

pyvista_stl-0.5.0-cp311-cp311-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (67.2 kB view details)

Uploaded Aug 12, 2026 CPython 3.11manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

pyvista_stl-0.5.0-cp311-cp311-macosx_11_0_arm64.whl (58.7 kB view details)

Uploaded Aug 12, 2026 CPython 3.11macOS 11.0+ ARM64

pyvista_stl-0.5.0-cp311-cp311-macosx_10_14_x86_64.whl (61.0 kB view details)

Uploaded Aug 12, 2026 CPython 3.11macOS 10.14+ x86-64

pyvista_stl-0.5.0-cp310-cp310-win_amd64.whl (249.9 kB view details)

Uploaded Aug 12, 2026 CPython 3.10Windows x86-64

pyvista_stl-0.5.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (71.8 kB view details)

Uploaded Aug 12, 2026 CPython 3.10manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

pyvista_stl-0.5.0-cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (67.4 kB view details)

Uploaded Aug 12, 2026 CPython 3.10manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

pyvista_stl-0.5.0-cp310-cp310-macosx_11_0_arm64.whl (58.9 kB view details)

Uploaded Aug 12, 2026 CPython 3.10macOS 11.0+ ARM64

pyvista_stl-0.5.0-cp310-cp310-macosx_10_14_x86_64.whl (61.3 kB view details)

Uploaded Aug 12, 2026 CPython 3.10macOS 10.14+ x86-64

File details

Details for the file pyvista_stl-0.5.0.tar.gz.

File metadata

Download URL: pyvista_stl-0.5.0.tar.gz
Upload date: Aug 12, 2026
Size: 27.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyvista_stl-0.5.0.tar.gz
Algorithm	Hash digest
SHA256	`b7114a1e1d7f14b7abbd8465db60dad0b661dc6636aa96cb09432ce1f3403385`
MD5	`96b412e4d215a2cc5d70e5b96a46a2e4`
BLAKE2b-256	`48eec093e7b5378408cd079ab85a1a102a725005beb476cef0041d40adc9fd59`

Algorithm	Hash digest
SHA256	`3729584368bb54e3c101f5e15a7f54ba060c27139a57f2f9657bfc81aaf28ab1`
MD5	`2fde92554d8ce21dc23597b48935580f`
BLAKE2b-256	`51fd76a455d4f13b7a46b40565b951a13fd9bdc401534cfe874527920f6ba040`

Algorithm	Hash digest
SHA256	`53310f17e5410dcbe7c47acdba64df8585dba7656e1ad5eae94b0340d70d1ba7`
MD5	`89c76961af75e4389c855d7f427a20f1`
BLAKE2b-256	`90e5257ca648e343197bb4320fd4b3eef229795cd3e70b750eb4eb86f16d2662`

Algorithm	Hash digest
SHA256	`f4aa9b5f09928d0066a8d8705de231ba048a237dfddbc2fec6a8fac43595c2f3`
MD5	`ddd8cf713077675fb5072890959fc745`
BLAKE2b-256	`3b0120f6e95c4c2b21671f8232343e9deea339d62ef19fb4a093de46e7e1576d`

Algorithm	Hash digest
SHA256	`55b312c7d74f28ed77f0008032ad3e818186c4d4ba70bc28f6d13a9d9e89d9e6`
MD5	`2116be44e477582b81b4a61a8c46f34c`
BLAKE2b-256	`e6d996b87c4335bf2eccdd1f555c098de4f8b796058ba793aa1630b7df00bd12`

Algorithm	Hash digest
SHA256	`8e77fb948685dcbd257db4d56784b8dce816a27ec635b635edde13b0c7f5dc40`
MD5	`1947d0c9583c235c3225cda20418b30b`
BLAKE2b-256	`d4884a6361544a53fe0c72a1ce4378a955e2beffb40c4bfa3a809abf3a1acff2`

Algorithm	Hash digest
SHA256	`b1fc167c759624139b795bf4afecda82e5ce3e1ba85fcda155a9e80ceff574d9`
MD5	`619e2166bee34cb2b740a89a89e5ffdf`
BLAKE2b-256	`81e625f9c48a8c69dd0d495cfdd37be09ab98d46917b234f8dc318d1ba8d1bf7`

Algorithm	Hash digest
SHA256	`95bfbb8a3e46a7122a9783341a3d9bcf22352744145db79223572a608643b3bc`
MD5	`4e936e754d0e7a0e2a022b9ce38afd82`
BLAKE2b-256	`6eaee3cbf382f81b0536547c7d3d1f6c9354dd35094c79d66b5996d81d8c58b9`

Algorithm	Hash digest
SHA256	`856c1239c2e8f42af7fa7625228936b944a6af2bd4267df7664f801c0c7c03bf`
MD5	`293f494c62b90af76763104b92c2f5e8`
BLAKE2b-256	`fdda3341f7dc39c771f0efd4e3aeeae1fba21d11bf8217ee5f3791e260e6def0`

Algorithm	Hash digest
SHA256	`43c21ed70bc3955cbdebba92293b05f0b6ed83c5a572e21268245d182eb9cfdd`
MD5	`30b48321480a6a3f085a94fa8b231791`
BLAKE2b-256	`be3b39f646c7e22e746699399a6b377aaa717871864f0c9bb292f7c4e3ba4f33`

Algorithm	Hash digest
SHA256	`410e5d010d27733557df94dbbe0e4d55362f091f4a3322c7c00bf033dc5a2d69`
MD5	`3185854b9e0a19eb656fc0e171ee33ae`
BLAKE2b-256	`d67bb920b69642946638cbb9f8cfe10a774c6d832187ff3398c1face25e5519e`

Algorithm	Hash digest
SHA256	`92db5680eb47a0219584dbd9cdad679eaf41fbd32c4eb4a7f6cd8114a824c396`
MD5	`ccc4b686893328bea9beb9b25bb973ea`
BLAKE2b-256	`0e2309f4ec1e51f3c8bbedc3ed4fb2d9ce5de5cdef5f4ea6e5254bfa27f048a4`

Algorithm	Hash digest
SHA256	`f1310cdc2278c38733b0aa39968678321922115e929b8cfe59c3a2503470c9f0`
MD5	`c4fe3ecf6edab109559e2780bfdce45b`
BLAKE2b-256	`c790369b97dbb77f049741c727c68a3427664d9d0c7694096ef07cc8bd6dc59e`

Algorithm	Hash digest
SHA256	`27fe5030ae0d2989838437bb443e4c71dd6f4c1d6bb6325c79232627a9a0a418`
MD5	`56c93bf3be6f81a2cb13108890c361c7`
BLAKE2b-256	`4322b9b464e9f062ab9843a49a1d09230eb640a0d7342148fce93ee6661eff5b`

Algorithm	Hash digest
SHA256	`f38a83a64392e34f924f16b48b729eaa70fee0676692e5d8babfd156a31d54d9`
MD5	`90b1a3e64b7a4ba39c065671fe7c1067`
BLAKE2b-256	`e36eecce71b504190149c69c667477f94f9af3defb84b76f69b78be108f3506c`

Algorithm	Hash digest
SHA256	`bdfc295dae5b73d1fa9e5db7d86ce347d857fb4b720a5574754d105c807ce06d`
MD5	`58947ee5edb9fd95951ec89781ac62a1`
BLAKE2b-256	`f4fa16dbe5f153f24a16d126c32db1ee8e69b3fcbf2299f9515c79de771d7664`

Algorithm	Hash digest
SHA256	`2802575495d0fa640e39e4666705d16795fad48a257cda23fa4a4a193d482925`
MD5	`1c3fc43b2f3910c963d201f13678378e`
BLAKE2b-256	`94f822b4cc42bc2681ddedaf8a6b6d045ad50eefbd5bfb555a9ff0f9232e3c26`

Algorithm	Hash digest
SHA256	`bc586c6bbad911c38558fb775d9db4c7ac7c236d3e7b592f13ac617043949e37`
MD5	`4096967f8c53e4e30508905b6d1f0828`
BLAKE2b-256	`fe7ed72fb591c9b1b9a126142b79f97d5f3239e44ea523afd5b82b197fbe4de4`

Algorithm	Hash digest
SHA256	`9356d8001aa19dba0599b53bbd2c970654bad720f76a9d2a09c72ac1aa711532`
MD5	`34c55c8b566415c34136937d82c380c3`
BLAKE2b-256	`404b3bade9b16e6d5b8aba50e5ba55bfe9604a34a0b584a1f71b2dc74e9281ef`

Algorithm	Hash digest
SHA256	`2ba74778c33cb8700ef7ba3233eb2aa43c129f675742cdf197b81452eb04b287`
MD5	`b1e23e8cfb8980e10b52177cc9206aa3`
BLAKE2b-256	`63eaef88e8b0dc05f3cf1db3e947ff83f8cdfc3a63a47803fa08cae1d1da24e0`

Algorithm	Hash digest
SHA256	`dfa3cebe2b73a330aaa248412a69e8f8233ebb6f1266e95904f83233f04b4bbf`
MD5	`1bd3de23889fd75c768f5630eb4e6e29`
BLAKE2b-256	`ec8efa309197f500e6fa8fb3e9289a359111f37d96b5785c7b94c6a33aa95946`

pyvista-stl 0.5.0

Installation

Usage

Benchmarks

Comparison with VTK across mesh sizes

Configuration

License and acknowledgments

Support

Project links

Key dates

Owner

Credits

GitHub Statistics

License expression

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Algorithm	Hash digest
SHA256	`246ec289f14ac33baecc7fb3fda45b0372b5527a3775ec9ed1a484c94e9d7d84`
MD5	`ca86251e9e59d6f78eb101f0feb14b23`
BLAKE2b-256	`6a066fef435437864e7a172576bb9a186021c412246bf6502139151880a34763`

Algorithm	Hash digest
SHA256	`fd3cf1635ed47b0567c4f82377c8ee56105edbb76d78da57b7cab46ce3f738c8`
MD5	`8294682703b810f9b86e83cd8af71f35`
BLAKE2b-256	`da1552d13160af6c7a4a4229067cb32b0cff44bf522e77c717d6d7fbb1598258`

Algorithm	Hash digest
SHA256	`bc4a401215d3c9acaebfbad0b44860be9e5ae2f2c26eca659b4810c396018519`
MD5	`ebea7b0838b72cd6606900f2913bc802`
BLAKE2b-256	`c444f4c2102564cd5ca616799c5ffa749c8e08bbdd7ba48c5be5b93ca933a11e`

Algorithm	Hash digest
SHA256	`30beaf140ebd895eb423b7f784048351df088f33164e1a7c7b5fd09dd4925db6`
MD5	`17f49e914348d752991c950e6224ebfa`
BLAKE2b-256	`011bde06bd95120dd944ec34291da47e58d9096d22b6b3a465237a76aa2f00c6`

Algorithm	Hash digest
SHA256	`0a9b2e8a3055edcd84a8c39eb75214afb9b724af5b0027854b6e34a54a0c5045`
MD5	`d1765a6c8b3cc3c27545df8624dd6b59`
BLAKE2b-256	`2d342b86d4c38e647370966025d3a8b692569e4a6925dde3684cb98e7ca04b3e`