|
MeshLib Documentation
|
|
MeshLib Documentation
|
The first part of this video shows MeshLib Python Installation process on Windows
When pip is done, confirm the result with Verify the installation — one command, with the output to expect. If a step fails, see Troubleshooting at the end of the Installation Process section.
Before installing MeshLib SDK for Python, ensure you have the following:
MeshLib supports the Python versions listed below. We recommend 3.12 or newer: Python 3.8 (end-of-life since October 2024) and 3.9 (end-of-life since October 2025) no longer receive security updates, and remain listed only because the published wheels still install on them.
Please install MeshLib using pip on these platforms.
Download a supported version of Python.
The PyPI page always shows the Python versions supported by the latest release.
You can use any Python-compatible editor, such as Visual Studio Code, PyCharm, or any IDE you prefer.
The wheel ships type stubs (.pyi) for every module, so editors such as VS Code (Pylance) and PyCharm offer completion and signature help for the MeshLib API with no extra setup.
MeshLib is available on PyPI for Windows, macOS, and Linux:
It installs two packages: meshlib-core — the headless core with mrmeshpy, mrmeshnumpy and mrcudapy — and the meshlib wheel on top of it, adding the interactive viewer (mrviewerpy) with its UI resources. numpy (>= 1.19) is the only external dependency.
On Windows that command works as written. A virtual environment is still worth using once you have more than one project, so their dependencies cannot collide:
On Linux, and on macOS with Homebrew Python, the plain command is refused before it downloads anything — error: externally-managed-environment — because pip will not install into an interpreter the system package manager owns (PEP 668); Apple's Command Line Tools Python instead accepts it quietly into a per-user directory you did not choose. There, install into a virtual environment:
On servers, in docker images, and in CI — anywhere the interactive viewer is never opened — install just the core:
The download is about 30% smaller and provides everything except meshlib.mrviewerpy; every other import (from meshlib import mrmeshpy, mrmeshnumpy, mrcudapy) works exactly as with the full package. Installing meshlib later adds the viewer on top, and pip uninstall meshlib removes only the viewer part again. Both packages are versioned in lockstep: meshlib of a given version requires exactly meshlib-core of the same version.
Releases up to 3.1.3 shipped a single meshlib wheel that owned every file meshlib-core provides now. Over such an installation pip install --upgrade meshlib reports success and leaves a broken package: pip installs the new meshlib-core first, then removes the old meshlib together with every file it used to own, including the mrmeshpy module that meshlib-core has just written, and finally installs the new viewer-only meshlib. Afterwards pip show meshlib-core prints the new version, but from meshlib import mrmeshpy fails with ModuleNotFoundError: No module named 'meshlib.mrmeshpy'.
Uninstall the old version before installing the new one:
If the upgrade has already happened, a forced reinstall repairs it in place:
Clean installs into a new environment, and upgrades between 3.1.4 and later versions, are not affected.
pip install reporting success is not the same as a working install: the wheel is tens of megabytes of prebuilt native code, and it can install cleanly and still fail to load. This one command covers the whole chain — import the package, load the native module, run a real geometry call:
Expected output — the path is yours and ends in mrmeshpy.pyd on Windows, while the two counts are fixed:
If it prints those two lines and exits 0, the installation is working. Anything else — a traceback, a loader error, no output — means it is not: see Troubleshooting below. The printed path is worth a glance too, since it names the environment that actually received the package.
With the install confirmed, the same call is the starting point of a real script — this one also writes the cube to a file:
Output:
The failures installations actually hit, with the message each one produces. Two of them leave pip install reporting success, which is what Verify the installation is for.
| Path | Symptom | Cause | Fix |
|---|---|---|---|
| Linux distribution Python, Homebrew Python on macOS | pip install meshlib stops before downloading anything with error: externally-managed-environment, then × This environment is externally managed. | Not a MeshLib problem: pip 23.0 and newer refuse to install any package into an interpreter the OS package manager owns (PEP 668, marked by a EXTERNALLY-MANAGED file next to the standard library). | Install into a virtual environment, as Installation Process above shows. pip install --break-system-packages meshlib also installs, but into the system interpreter — prefer the virtual environment. |
| Any | ERROR: Could not find a version that satisfies the requirement meshlib (from versions: none), then ERROR: No matching distribution found for meshlib. | No published wheel matches this interpreter: the Python version is outside the range in Prerequisites above, the interpreter is 32-bit, or the platform has no wheel at all — on ARM64 Windows the wheels start at Python 3.11, so an older interpreter there needs the x64 build. | Check what pip is matching against — python -c "import sys, sysconfig; print(sys.version, sysconfig.get_platform())" — and install a Python listed in Prerequisites. |
| Any | Install and import both succeed, but a documented function is missing — AttributeError: module 'meshlib.mrmeshpy' has no attribute ... — or pip show meshlib prints a version well behind the latest. | The package requires Python 3.8 or newer overall, but each release's wheel tags are narrower than that and change over time. When no wheel of the newest release matches your interpreter, pip does not fail: it silently installs the newest older release that does. | pip show meshlib, and compare with the version on the PyPI page. If it is behind, move to a Python version listed in Prerequisites and reinstall with pip install --upgrade --force-reinstall meshlib. |
| Any, after pip install --upgrade meshlib over 3.1.3 or older | pip reports success and pip show meshlib-core prints the new version, but from meshlib import mrmeshpy fails with ModuleNotFoundError: No module named 'meshlib.mrmeshpy'; site-packages/meshlib/ holds only mrviewerpy and a font. | Removing the old single-wheel meshlib deleted the files the new meshlib-core had just installed into the same directory, see Upgrading from 3.1.3 or older. | pip install --force-reinstall meshlib. |
Anything not listed here: please open an issue at MeshLib Issues, quoting the full pip output or traceback.
The meshlib package ships four importable modules:
| Module | Purpose |
|---|---|
| mrmeshpy | Core geometry: mesh and point-cloud I/O, boolean operations, offsets, decimation, remeshing, measurements |
| mrmeshnumpy | Conversion between MeshLib objects and NumPy arrays |
| mrviewerpy | The interactive Viewer — open a window and display meshes from Python |
| mrcudapy | CUDA-accelerated variants of selected algorithms |
Import them from the package, for example from meshlib import mrmeshpy.
MeshLib provides a set of example scripts that are available here. These examples are helpful for both developers and testers. Additionally, the Python library allows you to explore all the available functions in mrmeshpy using the standard help(meshlib.mrmeshpy) command.
After installing MeshLib, a great way to start exploring its capabilities is through interactive examples.
These examples are a great entry point for integrating MeshLib into your workflow, regardless of your operating system.
1.14.0