PyMeshLab

Common errors

• ModuleNotFoundError: No module named 'pymeshlab'

  cause The pymeshlab package is not installed or not available in the current Python environment.
  fix Run `pip install pymeshlab` to install the library.

• RuntimeError: Your glibc version (X.YY) is too old. PyMeshLab needs at least glibc 2.31.

  cause The system's GNU C Library (glibc) version is older than the minimum required by PyMeshLab's compiled components.
  fix This 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.

  cause The specified filter name is incorrect, or the parameters provided do not match the filter's signature in MeshLab's underlying library.
  fix Double-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

  cause 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).
  fix Ensure 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

  cause The specified mesh file path does not exist, is incorrect, or the file is corrupted/unreadable.
  fix Verify 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).

Warnings

• breaking Older Linux systems may encounter runtime errors due to glibc version requirements. PyMeshLab enforces installation only on systems with `glibc >= 2.31`.
  Fix: Ensure 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.`
• gotcha PyMeshLab releases often update their supported Python versions. Newer PyMeshLab versions may drop support for older Python versions, and vice versa.
  Fix: Check 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.
• gotcha Compatibility 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.
  Fix: If 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.
• gotcha Processing 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.
  Fix: For extremely large meshes, consider downsampling or simplifying them before processing, or ensure you have ample RAM available. Monitor memory usage during operations.

Install

• pip install pymeshlab Install stable version

Imports

• MeshSet

  import pymeshlab as ml
  ms = ml.MeshSet()

Quickstart

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.")