Self-hosted service
mikedh/trimesh avatar
mikedh/trimesh

trimesh: a numpy-only mesh library whose features switch on one soft dependency at a time

Python library for loading and using triangular meshes.

3,730 stars716 forksPythonMIT

At a glance

What is it?
trimesh loads, repairs, slices and analyzes triangular meshes in pure Python 3.10+. The core install needs only numpy, and every heavier feature waits on an extra package you add yourself.
Who is it for?
Choose trimesh if you work in Python, care about watertight solids, and are comfortable pinning a version because the API is not guaranteed stable. Look elsewhere if you need a viewer that works without the pyglet window or a stable API across major versions.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 1 day ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • mikedh/trimesh3,730 ★ · +36
Star history
Repository2026-10-082026-11-21
mikedh/trimesh3.7k3.7k

36 Stars in the last 44 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

numpy is the only hard dependency, and a bare install already reads STL, PLY, OBJ and GLTF

Keeping trimesh easy to install is a stated core goal, so the package requires only `numpy` (the metadata pins `numpy>=1.21`) and asks for Python 3.10 or newer. The minimal install is one command:

bash
pip install trimesh

That bare install can load many supported formats into `numpy.ndarray` values, including STL, PLY, OBJ and GLTF/GLB. Everything past loading is optional. Convex hulls need `scipy`, graph operations need `networkx`, and fast ray queries need `embreex`. Vector path handling uses `shapely` and `rtree`, XML formats such as 3DXML, XAML and 3MF use `lxml`, preview windows use `pyglet`, and faster cache checks use `xxhash`.

The design has a price. Code that calls a convex hull on a numpy-only install will fail until `scipy` is present, and the failure only shows up at the call, not at import time. Read the dependency overview on trimesh.org before you ship, and add each package your pipeline touches to your own requirements file instead of relying on a developer machine that happens to have them.

The easy extra covers three platforms, and the project tells you not to freeze with it

For people who want most of the soft dependencies in one step, there is an extra:

bash
pip install trimesh[easy]

It collects the soft dependencies that generally install cleanly from binaries with `pip` on Linux x86_64, MacOS ARM and Windows x86_64. That list of platforms is the limit. On anything else, the extra can pull in packages that need a compiler, and the install may stop partway.

The project's own advice for a different platform, or for an application that freezes its dependencies, is to skip extras. Depend on `trimesh scipy` and name every package, instead of `trimesh[easy]`. The reason is control. An extra is a moving set, so two builds a month apart can resolve to different contents even when the trimesh version is identical.

The advanced installation page on trimesh.org covers the remaining cases. Docker users have another route: images are published as `trimesh/trimesh` on Docker Hub, with a container guide in the docs, and the repository Makefile builds and tags those images with the latest tag, the version and the git short hash.

Trimesh merges vertices and drops NaN values on load unless you pass process=False

Constructing a mesh does more than store arrays. By default, trimesh does a light processing step that removes any NaN values and merges vertices that share a position. A mesh built from raw vertices and faces can therefore have fewer vertices than the array you passed in, and face indices are remapped to match.

To keep the data exactly as given, pass `process=False`:

python
import trimesh

mesh = trimesh.Trimesh(
    vertices=[[0, 0, 0], [0, 0, 1], [0, 1, 0]], faces=[[0, 1, 2]], process=False
)

This matters for any workflow that compares vertex counts or indices before and after loading, such as matching a mesh to a separate attribute table. The merge is also what lets later checks see shared edges, so turning it off has a consequence. A file that stores each triangle with its own copy of every corner will look like a set of unconnected triangles, and a watertight test on it will say no.

To see messages from the library while you experiment, `trimesh.util.attach_to_log()` attaches it to the logger so they print to the console.

Booleans, ray queries and slicing each depend on a different optional engine

The feature list is long, and most of its items rest on something outside numpy. Boolean operations (intersection, union, difference) run through Manifold3D or Blender. Splitting a mesh by face connectivity uses networkx or scipy.sparse. Ray-mesh queries return location and triangle index, and `embreex` speeds them up.

Slicing has two forms. A cross section gives a 2D outline, and a slice produces a 3D remainder mesh, the case used for 3D printing. Other calculations include face adjacencies, face angles, vertex defects, convex hulls, mass properties (volume, center of mass, moment of inertia and principal components of inertia), nearest point on the surface, signed distance and approximate minimum volume oriented bounding boxes and spheres. The same list covers surface sampling and subdividing faces.

The cost is that one pipeline can need five extras. A boolean step with Blender as the engine needs Blender installed on the machine, which a container image has to provide on its own. With no engine present, the boolean call cannot run. The repository offers `examples/` scripts such as `convexify.py`, `section.ipynb`, `ray.py` and `voxel.py` that show several of these calls in context.

Voxelizing and smoothing assume a watertight mesh, so repair comes first

Trimesh puts an emphasis on watertight surfaces, and the feature list shows where it applies. Voxelization and smoothing are both listed for watertight meshes. The smoothing choices are Laplacian algorithms in three flavors: Classic, Taubin and Humphrey.

A mesh straight from a scan or a CAD export often has holes. The library can check whether a mesh is watertight or convex, and it can repair simple problems with triangle winding, normals, and quad or triangle holes. The word simple is the limit. Large gaps, self-intersections and badly broken topology are not in the list of things it fixes, so a damaged mesh may still fail the watertight check after repair, and a voxelization of it is off the table.

Two related tools help with cleanup. A rotation, translation and tessellation invariant identifier lets you find duplicate meshes, and the hashing system tracks changes on a subclassed numpy array using MD5, zlib CRC or xxhash, caching expensive values until the data changes. Primitive objects (Box, Cylinder, Sphere, Extrusion) are subclasses of Trimesh and carry the same inertia and viewer features.

The API is mostly stable, but only an exact version pin protects a deployment

The project is plain about compatibility. The API is mostly stable, but that should not be relied on and is not guaranteed. Anyone deploying something built on trimesh should install a specific version. The package metadata labels the status as Development Status 4, Beta, and lists Python 3.10 through 3.13.

Breaking changes are supposed to give warning. Trimesh API changes should generally have a one-year period of printing a `warnings.DeprecationWarning`, although that is not always possible. The example the project gives is the pyglet2 viewer rewrite, which has been back-burnered for several years. A pinned version avoids the surprise, but you give up fixes, so schedule an upgrade test around the deprecation warnings that your logs already show.

The import side is where drift would hurt most, since a loader change can alter how a file maps to arrays. Pin the version, run your own sample files through new releases in a branch, and compare vertex and face counts before you merge. Preview is the other soft spot. The viewer uses an OpenGL `pyglet` window, or three.js inline in jupyter or marimo notebooks, and the dependency set differs between the two.

Recent release cadence: three versions between August and late October 2026

The repository is not archived, and its last push was on 2026-10-25. Version 5.2.0 was released on 2026-10-24, 5.1.1 on 2026-10-02 and 5.1.0 on 2026-08-31. The `pyproject.toml` in the repository carries `version = "5.2.0"`, and the license is MIT, so the answer to whether trimesh is free to use is yes, with the license file in the repository root.

The repository layout shows what ships beside the code. There are `tests/`, `docs/`, `helpers/` (which holds the Dockerfile), `models/` and a long `examples/` folder with scripts for section, nearest-point, texture, voxel and offscreen rendering work. The package also installs a `trimesh` command defined in `pyproject.toml` as `trimesh:__main__.main`.

Pull requests are described as appreciated and responded to promptly, and a contributing guide sits on trimesh.org. If you have a say in the file format, the project suggests trying GLB as a fast modern option, while the export list also includes GLTF, binary STL, binary PLY, ASCII OFF, OBJ and COLLADA. Two vector path formats, DXF and SVG, can be imported and exported for 2D or 3D paths.

Editorial conclusion

Choose trimesh if you work in Python, care about watertight solids, and are comfortable pinning a version because the API is not guaranteed stable. Look elsewhere if you need a viewer that works without the pyglet window or a stable API across major versions. Before committing, install only numpy and load one of your own files, then list which soft dependencies your pipeline needs.

Frequently asked questions

What is a trimesh?

trimesh is a pure Python 3.10+ library for loading and using triangular meshes, with an emphasis on watertight surfaces. Its Trimesh object is modeled on the Polygon object in the Shapely library.

Is trimesh free to use?

Yes. trimesh is released under the MIT license, and the repository is public on GitHub.

How do I install trimesh using pip?

Run pip install trimesh for the minimal install, which needs only numpy. To add the soft dependencies that install cleanly from binaries on Linux x86_64, MacOS ARM and Windows x86_64, run pip install trimesh[easy].

trimesh is watertight: how does the library check it?

The feature list includes checking whether a mesh is watertight or convex. It also lists repair of simple problems with triangle winding, normals, and quad or triangle holes.

Official sources

  1. License: MIT
  2. mikedh/trimesh on GitHub
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/mikedh-trimesh.svg)](https://hysenlabs.com/projects/mikedh-trimesh)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/mikedh-trimesh.svg)](https://hysenlabs.com/projects/mikedh-trimesh)

Was this useful?