numpy-stl

CI PyPI Python Downloads Documentation License

A fast library for reading, writing, and modifying STL files, powered by NumPy. Every mesh operation uses vectorized array math for speed.

Stanford Dragon — 871,414 triangles loaded in 0.63s, rendered with matplotlib

Stanford Dragon rendered with matplotlib

Quick Start

pip install numpy-stl

from stl import mesh

# Load an STL file (auto-detects binary/ASCII)
your_mesh = mesh.Mesh.from_file('model.stl')

# Inspect
print(f'{len(your_mesh)} triangles')
print(f'Bounding box: {your_mesh.min_} to {your_mesh.max_}')

# Save
your_mesh.save('output.stl')

Features

  • Read and write binary and ASCII STL files
  • Read PLY and 3MF files (3MF is experimental, read-only)
  • Mesh operations: rotate, translate, transform (4x4 matrix)
  • Properties: surface area, volume, center of gravity, inertia tensor, convexity
  • Combine multiple meshes by concatenating data arrays
  • CLI tools: stl, stl2ascii, stl2bin for format conversion
  • Fast: all operations backed by NumPy vectorized math

Supported Formats

Format Read Write Notes
STL (binary) ✅ ✅ Auto-detected on load
STL (ASCII) ✅ ✅ ~5x faster with optional speedups
PLY ✅ ✅ Binary and ASCII; from_ply_file / save_ply
3MF ✅ — Experimental; from_3mf_file

Requirements & Compatibility

  • Python: 3.10+
  • NumPy: 1.24+ (installed automatically)
  • Platforms: Linux, macOS, Windows
  • Optional: numpy-stl[fast] for the Cython ASCII speedups (see below)

Performance / Optional Speedups

numpy-stl is fast out of the box. For even faster ASCII STL I/O, install the optional Cython speedups:

pip install numpy-stl[fast]

This installs the speedups package, a compiled C extension for ASCII parsing. The library works identically without it -- pure Python is the default.

Benchmark

ASCII STL read performance — ~5x faster with the speedups C extension, consistent across data sizes (median of 5 runs):

ASCII STL Read Performance

Facets Pure Python Speedups Factor
10,000 36 ms 7 ms 5.1x
100,000 0.36 s 73 ms 4.9x
871,414 3.10 s 0.59 s 5.2x
1,000,000 3.60 s 0.73 s 4.9x

Note: Results will vary by hardware. Run the benchmark yourself: python benchmarks/benchmark_ascii_read.py

Usage Examples

Creating a Mesh from Scratch

import numpy as np
from stl import mesh

# Define vertices and faces of a cube
vertices = np.array([
    [-1, -1, -1], [+1, -1, -1], [+1, +1, -1], [-1, +1, -1],
    [-1, -1, +1], [+1, -1, +1], [+1, +1, +1], [-1, +1, +1],
])
faces = np.array([
    [0, 3, 1], [1, 3, 2], [0, 4, 7], [0, 7, 3],
    [4, 5, 6], [4, 6, 7], [5, 1, 2], [5, 2, 6],
    [2, 3, 6], [3, 7, 6], [0, 1, 5], [0, 5, 4],
])

cube = mesh.Mesh(np.zeros(faces.shape[0], dtype=mesh.Mesh.dtype))
for i, f in enumerate(faces):
    for j in range(3):
        cube.vectors[i][j] = vertices[f[j], :]

cube.save('cube.stl')

Rotating and Translating

import math
from stl import mesh

m = mesh.Mesh.from_file('model.stl')
m.rotate([0, 0, 1], math.radians(90))
m.translate([10, 0, 0])
m.save('transformed.stl')

Mass Properties

from stl import mesh

m = mesh.Mesh.from_file('closed_model.stl')
volume, cog, inertia = m.get_mass_properties()
print(f'Volume: {volume:.4f}')
print(f'Center of gravity: {cog}')

Combining Meshes

import numpy as np
from stl import mesh

m1 = mesh.Mesh.from_file('part1.stl')
m2 = mesh.Mesh.from_file('part2.stl')
combined = mesh.Mesh(np.concatenate([m1.data, m2.data]))
combined.save('combined.stl')

Plotting with Matplotlib

import math
from stl import mesh
from mpl_toolkits import mplot3d
from matplotlib import pyplot

figure = pyplot.figure(figsize=(8, 6))
axes = figure.add_subplot(projection='3d')

dragon = mesh.Mesh.from_ply_file('dragon_vrip.ply')
dragon.rotate([1, 0, 0], math.radians(-90))

axes.add_collection3d(
    mplot3d.art3d.Poly3DCollection(dragon.vectors)
)

scale = dragon.points.flatten()
axes.auto_scale_xyz(scale, scale, scale)
pyplot.show()

API Cheatsheet

Assumes import math, import numpy as np, from stl import mesh, and from stl import Mode (for the ASCII save).

Task Call
Load (auto-detect) mesh.Mesh.from_file('m.stl')
Load PLY mesh.Mesh.from_ply_file('m.ply')
Load 3MF (experimental) list(mesh.Mesh.from_3mf_file('m.3mf'))
Save (auto/format) m.save('out.stl')
Save as ASCII m.save('out.stl', mode=Mode.ASCII)
Save PLY m.save_ply('out.ply')
Rotate (axis, radians) m.rotate([0, 0, 1], math.radians(90))
Translate m.translate([x, y, z])
Transform (4x4 matrix) m.transform(matrix)
Bounding box m.min_, m.max_
Mass properties volume, cog, inertia = m.get_mass_properties()
With density vol, mass, cog, inertia = m.get_mass_properties_with_density(d)
Combine meshes mesh.Mesh(np.concatenate([a.data, b.data]))

CLI Tools

# Convert ASCII to binary
stl2bin input.stl output.stl

# Convert binary to ASCII
stl2ascii input.stl output.stl

# Auto-detect and convert
stl input.stl output.stl

Documentation

Full documentation is available at numpy-stl.readthedocs.io.

Contributing

Contributions are welcome! See CONTRIBUTING.md for the development setup guide.

Links

License

BSD-3-Clause

Project links

Data verified by PyPI on Jun 17, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for jhammudoglu from gravatar.com jhammudoglu Avatar for wolph from gravatar.com wolph

Credits

Author: Rick van Hattem

GitHub Statistics

Data verified by PyPI on Jun 17, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

BSD-3-Clause
View SPDX License List

Requires

Python >=3.10

Provides Extra

dev docs fast tests tox

Classifiers

Report project as malware

Download files

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

Source Distribution

numpy_stl-4.0.0.tar.gz (29.4 kB view details)

Uploaded Source

Built Distribution

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

numpy_stl-4.0.0-py3-none-any.whl (32.3 kB view details)

Uploaded Python 3

File details

Details for the file numpy_stl-4.0.0.tar.gz.

File metadata

  • Download URL: numpy_stl-4.0.0.tar.gz
  • Upload date:
  • Size: 29.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for numpy_stl-4.0.0.tar.gz
Algorithm Hash digest
SHA256 086579c101fb2df9fb2594db7074728345710c931265cfdae4a50ed8d59d2f7e
MD5 62c2afa89109a53a46827e22910155ec
BLAKE2b-256 3cd401be5c1170ad58dd5cb028ea3329e756cc1c8e9a3fc44784953bccb81771

See more details on using hashes here.

Provenance

The following attestation bundles were made for numpy_stl-4.0.0.tar.gz:

Publisher: publish.yml on wolph/numpy-stl

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file numpy_stl-4.0.0-py3-none-any.whl.

File metadata

  • Download URL: numpy_stl-4.0.0-py3-none-any.whl
  • Upload date:
  • Size: 32.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for numpy_stl-4.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 8ee1413d12699c8a97821dc5d5f105d047c1aeecc3869dfcf1d92b50272da59c
MD5 7a52c178bc0a8703573df950de016887
BLAKE2b-256 791fb76289a9a82df2062274001a3500ca56774c1ee0ddb7e31ee688a48dd9f7

See more details on using hashes here.

Provenance

The following attestation bundles were made for numpy_stl-4.0.0-py3-none-any.whl:

Publisher: publish.yml on wolph/numpy-stl

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

4.0.0 This release

2 files

3.2.0

2 files

3.1.2

2 files

3.1.1

2 files

3.1.0

2 files

3.0.1

2 files

3.0.0

2 files

2.17.1

2 files

2.17.0

2 files

2.16.3

2 files

2.16.2

2 files

2.16.1

2 files

2.16.0

2 files

2.15.1

3 files

2.15.0

2 files

2.14.2

2 files

2.14.1

2 files

Yanked

2.14.0

2 files

Yanked reason: Some binary STL files cannot be read with this release .

2.13.1

2 files

2.13.0

2 files

2.12.0

2 files

2.11.3

2 files

2.11.2

2 files

2.11.1

2 files

2.11.0

2 files

2.10.1

2 files

2.10.0

2 files

2.9.0

2 files

2.8.0

2 files

2.7.0

2 files

2.6.0

2 files

2.5.0

2 files

2.4.1

2 files

2.3.2

2 files

2.3.1

2.3.0

2 files

2.2.3

1 file

2.2.2

2 files

2.2.0

2 files

2.1.0

2 files

2.0.0

2 files

1.9.1

1 file

1.9.0

2 files

1.8.0

2 files

1.7.1

1 file

1.7.0

1 file

1.6.2

1 file

1.6.1

1 file

1.6.0

1 file

1.5.2

1 file

1.5.1

1 file

1.5.0

1 file

1.4.2

1 file

1.4.1

1 file

1.4.0

1 file

1.3.8

1 file

1.3.7

1 file

1.3.6

1 file

1.3.5

1 file

1.3.4

1 file

1.3.3

1 file

1.3.2

1 file

1.3.1

1 file

1.3.0

1 file

1.2.0

1 file

1.1.2

1 file

1.1.0

1 file

1.0.2

1 file

1.0.1

1 file

1.0.0

1 file

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page