Install & Compatibility
Where this runs
tested against v2025.7.post1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 7.7s · import 0.000s · 363MB
366MB installed
● package 366MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MeshSet
✓ import pymeshlab as ml
ms = ml.MeshSet()
This quickstart demonstrates how to initialize PyMeshLab's MeshSet, (optionally create a dummy mesh for demonstrative purposes, or ideally load an existing mesh), apply a common processing filter like decimation, and print some statistics. For actual use, replace the dummy mesh creation with `ms.load_new_mesh('/path/to/your/mesh.ply')` and `ms.save_current_mesh('/path/to/save/decimated_mesh.ply')`.
import pymeshlab as ml
import os
# Create a MeshSet object
ms = ml.MeshSet()
# Example: Load a mesh, apply decimation, and save it
# In a real scenario, replace with your actual mesh file path.
# For demonstration, we'll assume a 'teapot.ply' exists or skip loading.
# Path to a dummy input/output file for demonstration
input_path = os.path.join(os.getcwd(), "dummy_input.ply")
output_path = os.path.join(os.getcwd(), "dummy_output.ply")
# To make this runnable without an actual mesh file, we'll bypass actual file ops for new users
# In a real use-case, you'd load an existing mesh:
# ms.load_new_mesh(input_path)
# For this quickstart, let's create a simple mesh programmatically if no file
# This is not common for PyMeshLab, but makes the example runnable.
# In a real scenario, you would have loaded an actual mesh file.
# If you have a .ply file, uncomment the line below and point it to your file.
# ms.load_new_mesh("/path/to/your/mesh.ply")
# --- If you don't have a mesh file, this part makes the example executable ---
# Create a dummy mesh if no file is loaded (for quickstart execution only)
if ms.number_meshes() == 0:
print("No mesh loaded, creating a dummy mesh for demonstration...")
# This is a highly simplified dummy mesh creation, not typical PyMeshLab usage
# It's just to ensure the filter application doesn't fail immediately.
try:
ms.add_color_sphere(radius=1.0, quality=2)
print("Dummy sphere created.")
except Exception as e:
print(f"Could not create dummy sphere: {e}. PyMeshLab is best used with existing mesh files.")
# If even dummy creation fails, then the library isn't working as expected
# For this quickstart, we assume it works.
# --- End of dummy mesh creation ---
if ms.number_meshes() > 0:
print(f"Number of meshes before decimation: {ms.current_mesh().vertex_number()}")
# Apply a decimation filter (e.g., reduce mesh complexity by 50%)
# The parameters are specific to MeshLab filters.
ms.meshing_decimation_quadric_edge_collapse(TargetPerc=0.5)
print(f"Number of meshes after decimation: {ms.current_mesh().vertex_number()}")
# Save the modified mesh
# In a real scenario, ensure the output path is valid and writable
# ms.save_current_mesh(output_path)
# print(f"Decimated mesh saved to: {output_path}")
else:
print("No mesh available to process. Please load a valid mesh file for actual use.")
print("PyMeshLab quickstart complete.")
Debug
Known issues
breakingOlder Linux systems may encounter runtime errors due to glibc version requirements. PyMeshLab enforces installation only on systems with `glibc >= 2.31`.fixEnsure your Linux environment has `glibc` version 2.31 or higher. Consider updating your OS or using a newer Docker environment if you encounter `RuntimeError: Your glibc version (X.YY) is too old.`
affects: 2022.2.post4 onwards
gotchaPyMeshLab releases often update their supported Python versions. Newer PyMeshLab versions may drop support for older Python versions, and vice versa.fixCheck the PyPI page or GitHub releases for specific Python version compatibility. For example, `v2025.7.post1` adds support for Python 3.14, while `v2023.12.post3` added support for Python 3.13. Ensure your Python environment matches the library's requirements.
affects: All versions
gotchaCompatibility with NumPy 2.0 was explicitly added in version 2023.12.post2. Older versions of PyMeshLab might not work correctly or might produce warnings/errors with NumPy 2.0.fixIf using an older PyMeshLab version, stick to NumPy < 2.0. If you need NumPy 2.0, ensure you are using PyMeshLab 2023.12.post2 or newer.
affects: Prior to 2023.12.post2
gotchaProcessing very large meshes can be memory intensive and slow, potentially leading to out-of-memory errors or long processing times, as PyMeshLab leverages MeshLab's C++ backend.fixFor extremely large meshes, consider downsampling or simplifying them before processing, or ensure you have ample RAM available. Monitor memory usage during operations.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pymeshlab'
The pymeshlab package is not installed or not available in the current Python environment.
fixRun `pip install pymeshlab` to install the library.
RuntimeError: Your glibc version (X.YY) is too old. PyMeshLab needs at least glibc 2.31.
The system's GNU C Library (glibc) version is older than the minimum required by PyMeshLab's compiled components.
fixThis issue typically occurs on older Linux distributions. Upgrade your operating system, use a newer Docker image, or build PyMeshLab from source if your environment cannot meet the glibc 2.31 requirement.
ValueError: Filter 'meshing_decimation_quadric_edge_collapse' not found or invalid parameters.
The specified filter name is incorrect, or the parameters provided do not match the filter's signature in MeshLab's underlying library.
fixDouble-check the filter name for typos (they are case-sensitive). Consult the PyMeshLab documentation or MeshLab's filter list for correct filter names and their required parameters. For example, use `ms.apply_filter('filter_name', param1=value1, ...)`. numpy.core.multiarray failed to import
This usually indicates an incompatibility between a compiled extension (like PyMeshLab's backend) and the installed NumPy version, often occurring during major NumPy version upgrades (e.g., to NumPy 2.0).
fixEnsure your PyMeshLab version supports your NumPy version. If you are on NumPy 2.0, upgrade PyMeshLab to 2023.12.post2 or newer. If you are on an older PyMeshLab, consider downgrading NumPy to a compatible version (e.g., `pip install 'numpy<2.0'`).
Cannot load mesh from file: /path/to/non/existent/mesh.ply
The specified mesh file path does not exist, is incorrect, or the file is corrupted/unreadable.
fixVerify that the file path is correct and absolute, the file exists, and you have read permissions. Also, ensure the mesh file format is supported by MeshLab (e.g., .ply, .obj, .stl).
Upgrade
Version history
2025.7.post1latest on PyPI · released Jan 30, 2026
Audit
Dependencies
numpyrequiredRequired for mesh data manipulation and representation.