meshio

library5.3.5pypypi✓ verified 22d ago

meshio is a Python library for reading and writing various unstructured mesh formats, facilitating smooth conversion between them. It supports a wide array of formats including Abaqus, ANSYS msh, Gmsh, STL, VTK, XDMF, and many others. Currently at version 5.3.5, meshio is actively maintained with regular updates and requires Python 3.8 or newer. It can be used both as a command-line tool for conversions and as a Python API for programmatic mesh manipulation.

data serialization

pip install meshio

github ↗package ↗

INSTALL

IMPORT

SIG · MESHIO

meshio

datapythonv5.3.5

Install

5.3s avg

Import

580ms

Disk

133MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v5.3.5 · 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

musl

glibc

py 3.10

1/2 runs

✓ 5.25s

py 3.11

1/2 runs

✓ 5.1s

py 3.12

1/2 runs

✓ 4.9s

py 3.13

1/2 runs

✓ 5s

py 3.9

1/2 runs

✓ 6.2s

133MB installed

● package 133MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

meshio

✓ import meshio

This quickstart demonstrates how to create a mesh from points and cells, add associated data (point data, cell data), write it to a VTK file, and then read it back. The `meshio.Mesh` constructor takes points, a list of cell blocks (type and indices), and optional point/cell/field data. The `mesh.write()` method saves the mesh, and `meshio.read()` loads it.

import meshio import numpy as np # Define points (vertices) of the mesh points = [ [0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [1.0, 1.0, 0.0], [2.0, 0.0, 0.0], [2.0, 1.0, 0.0], ] # Define cells (elements) of the mesh, grouped by type # Here, two triangles and one quad cells = [ ("triangle", np.array([[0, 1, 2], [1, 3, 2]])), ("quad", np.array([[1, 4, 5, 3]])), ] # Create a Mesh object mesh = meshio.Mesh( points, cells, # Optionally provide extra data on points, cells, etc. point_data={"T": np.array([0.3, -1.2, 0.5, 0.7, 0.0, -3.0])}, # Each item in cell data must match the cells array structure cell_data={"a": [np.array([0.1, 0.2]), np.array([0.4])]} ) # Write the mesh to a file (format inferred from extension, or explicitly specified) mesh.write( "output.vtk", # file_format="vtk", # optional, inferred from extension binary=True # Write in binary format (e.g. for VTK) ) # Read a mesh from a file read_mesh = meshio.read("output.vtk") print(f"Read mesh points:\n{read_mesh.points}") print(f"Read mesh cells:\n{read_mesh.cells}") print(f"Read mesh point data (T):\n{read_mesh.point_data['T']}") print(f"Read mesh cell data (a):\n{read_mesh.cell_data['a']}")

meshio --version

Debug

Known issues

breakingBreaking changes in meshio versions 4.0.0 and newer, particularly concerning the internal representation and handling of mesh.cells, can cause compatibility issues with code written for older versions, especially when interfacing with other finite element libraries like FEniCS.

fix

Review and update code that accesses `mesh.cells` or `mesh.cell_data` directly. The structure for `cells` is a list of `(cell_type_string, numpy_array_of_indices)` tuples. Ensure compatibility with meshio's current data structures.

affects: >=4.0.0

gotchaFor full support of all advertised mesh formats (e.g., H5M, NetCDF, comprehensive XDMF features), `meshio` requires several optional dependencies. Without these, attempts to read or write specific formats will result in `ModuleNotFoundError` or similar errors.

fix

Install `meshio` with all optional dependencies using `pip install meshio[all]` or install specific dependencies (e.g., `h5py`, `netCDF4`, `lxml`) as needed for the desired formats.

affects: All

gotchaWhen constructing a `meshio.Mesh` object programmatically, the `cells` argument expects a list of tuples, where each tuple must contain a string identifying the cell type (e.g., "triangle", "quad", "tetra") and a NumPy array of node indices for that cell type. Misunderstanding or incorrectly formatting this can lead to errors, particularly with mixed cell types or incorrect node ordering.

fix

Always provide the `cells` argument as a list of `(cell_type_string, numpy_array_of_indices)` tuples. Refer to `meshio` documentation or source for exact cell type strings and expected node ordering for each type (e.g., `meshio._common.num_nodes_per_cell`).

affects: All

breakingOlder versions of `meshio` (prior to 5.3.5) exhibited compatibility issues with NumPy 2.0, leading to runtime errors or unexpected behavior.

fix

Upgrade `meshio` to version 5.3.5 or newer to ensure full compatibility with NumPy 2.0. If an upgrade is not possible, downgrade NumPy to a compatible version (e.g., NumPy 1.x).

affects: <5.3.5

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'meshio'

The `meshio` library is not installed in the Python environment being used, or the environment is not correctly activated.

fix

Install `meshio` using pip: `pip install meshio` or `pip install meshio[all]` to include all optional dependencies.

meshio._exceptions.ReadError: Could not deduce file format from path '...' (or 'Unknown section 'OFFSETS'')

The file extension does not clearly indicate a supported mesh format, the file itself is malformed, or the specific format/version is not supported by `meshio`'s automatic detection. For 'Unknown section 'OFFSETS'', it indicates an issue with parsing a specific VTK file structure.

fix

Explicitly specify the file format when reading using the `file_format` argument (e.g., `meshio.read('my_mesh.dat', file_format='tecplot')`). Ensure the file is a valid meshio-supported format and not corrupted. If the format is truly unsupported, consider converting it to a supported format using other tools.

ValueError: Incompatible cell data. Cell block X ('type') has length Y, but corresponding cell data item has length Z.

This error typically occurs when the `cell_data` provided for a mesh does not have the correct dimensions or number of entries corresponding to its associated cell block, particularly when reading or writing Gmsh files with multiple cell types.

fix

Ensure that each item in `cell_data` is an array whose length matches the number of cells in the corresponding `CellBlock`. If reading from a file, this might indicate an issue with the source file's consistency or a limitation in `meshio`'s handling of specific complex Gmsh structures.

Error writing GMSH format: "Can only deal with one cell type for now"

When writing to certain Gmsh file formats (e.g., Gmsh 2.2), `meshio` might be limited to handling only one type of cell (e.g., only triangles, or only quads) within a single cell block. If your mesh has mixed cell types (e.g., triangles and lines) in the data intended for a single Gmsh block, this error can occur.

fix

When creating the `meshio.Mesh` object, separate different cell types into distinct `CellBlock` entries or consider writing to a more flexible format like VTK or XDMF first, then converting using `meshio-convert` if a multi-cell-type Gmsh output is strictly necessary and supported by a newer Gmsh format version.

ValueError: could not convert string to float: '>>>'

This error often arises when `meshio` attempts to parse a numeric value from a string in a mesh file, but encounters unexpected non-numeric characters, commonly found in malformed ASCII STL files or other text-based mesh formats.

fix

Inspect the input mesh file (e.g., an STL file) for corrupted lines or unexpected characters. Ensure the file conforms strictly to the expected format specification. If possible, regenerate the mesh file from its source or try opening it in a dedicated mesh viewer to identify malformations.

Upgrade

Version history

5.3.5latest on PyPI · released Jan 31, 2024

Audit

Dependencies

numpyrequiredFundamental array manipulation for mesh data.

h5pyoptionalRequired for H5M and XDMF mesh formats.

netCDF4optionalRequired for Netgen mesh formats.

lxmloptionalRequired for some XDMF XML parsing.

richoptionalUsed for rich command-line output from the `meshio` CLI tools.

Agent activity

38 hits · last 30 days

node

Resources

githubhttps://github.com/nschloe/meshio ↗

packagehttps://pypi.org/project/meshio/ ↗