plyfile

library1.1.5pypypi✓ verified 22d ago

The `plyfile` Python module provides a simple, NumPy-based facility for reading and writing ASCII and binary PLY files, a common format for storing 3D surface meshes. It is currently at version 1.1.3 (released October 21, 2025) and maintains an active development status with several releases per year, as evidenced by its changelog and PyPI activity.

data serialization

pip install plyfile

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · PLYFILE

plyfile

datapythonv1.1.5

Install

3.8s avg

Import

242ms

Disk

89MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.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

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.230s · 89.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.8s · import 0.254s · 86MB

89MB installed

● package 89MB

Code

Verified usage

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

PlyData

✓ from plyfile import PlyData

✗ import plyfile; plyfile.PlyData

While `import plyfile` works, directly importing `PlyData` and `PlyElement` is the common and recommended practice for clarity and direct access.

PlyElement

✓ from plyfile import PlyElement

✗ import plyfile; plyfile.PlyElement

While `import plyfile` works, directly importing `PlyData` and `PlyElement` is the common and recommended practice for clarity and direct access.

This quickstart demonstrates how to create structured NumPy arrays representing vertices and faces, construct `PlyElement` and `PlyData` objects, write them to an ASCII PLY file, and then read the data back. It covers the basic workflow for both serialization and deserialization.

import numpy as np from plyfile import PlyData, PlyElement import os # 1. Prepare data for a PLY file vertices = np.array([ (0.0, 0.0, 0.0, 255, 0, 0), (1.0, 0.0, 0.0, 0, 255, 0), (0.0, 1.0, 0.0, 0, 0, 255), (1.0, 1.0, 0.0, 255, 255, 0) ], dtype=[('x', 'f4'), ('y', 'f4'), ('z', 'f4'), ('red', 'u1'), ('green', 'u1'), ('blue', 'u1')]) faces = np.array([ ([0, 1, 2],), ([1, 3, 2],) ], dtype=[('vertex_indices', 'i4', (3,))]) # 2. Create PlyElement instances vertex_element = PlyElement.describe(vertices, 'vertex') face_element = PlyElement.describe(faces, 'face') # 3. Create a PlyData instance plydata_to_write = PlyData([vertex_element, face_element], text=True, comments=['Created by plyfile quickstart']) output_filename = 'quickstart_output.ply' # 4. Write the PLY data to a file with open(output_filename, 'wb') as f: plydata_to_write.write(f) print(f"Successfully wrote PLY file: {output_filename}") # 5. Read the PLY data from the file with open(output_filename, 'rb') as f: plydata_read = PlyData.read(f) print("\nSuccessfully read PLY file:") print(plydata_read) print("Vertices:\n", plydata_read['vertex'].data) print("Faces:\n", plydata_read['face'].data) # Clean up the created file os.remove(output_filename) print(f"Cleaned up {output_filename}")

Debug

Known issues

breakingAs of `plyfile` version 1.1 (and later), official support for Python versions older than 3.9 and NumPy versions older than 1.21 has been removed. Users on older environments may encounter compatibility issues.

fix

Upgrade your Python environment to 3.9 or newer and NumPy to 1.21 or newer. `pip install --upgrade python numpy` or manage with your preferred environment tool.

affects: >=1.1

gotchaMemory mapping (`mmap` argument in `PlyData.read`) for faster binary data parsing has limitations with list properties. Elements containing *variable-length* list properties cannot be memory-mapped. For *fixed-length* list properties, the `known_list_len` dictionary argument is mandatory during `PlyData.read` to enable memory mapping.

fix

For fixed-length list properties, provide `known_list_len={'element_name': {'list_property_name': length}}` to `PlyData.read`. Avoid memory mapping for elements with truly variable-length list properties.

affects: All versions

gotchaWhen performing I/O operations, `plyfile` differentiates between text-mode and binary-mode streams. Text-mode streams (e.g., those returned by `sys.stdin` or `sys.stdout` or `open('file.ply', 'r')`) are only compatible with ASCII-format PLY files. Binary-mode streams (`open('file.ply', 'rb')` or `open('file.ply', 'wb')`) are required for all PLY file formats (ASCII and binary). Writing a binary-format PLY to a text stream will raise a `ValueError`.

fix

Always use binary mode (`'rb'` for reading, `'wb'` for writing) when opening PLY files to ensure compatibility with both ASCII and binary PLY formats, unless you specifically intend to work only with ASCII files via text streams.

affects: All versions

gotchaWhen creating PLY files using `plyfile`, there are restrictions on the data types supported by NumPy structured arrays that can be directly mapped to PLY properties. For instance, the PLY format does not directly support 64-bit integer or complex data types. While non-scalar fields are allowed and will be serialized as list properties, users should be mindful of these underlying PLY format limitations.

fix

Ensure that the NumPy structured array dtypes align with supported PLY data types (e.g., float, uchar, int). Convert unsupported types to compatible ones before creating `PlyElement` instances.

affects: All versions

gotchaWhen reading a PLY file, even if a non-scalar (e.g., fixed-size array) field was serialized as a list property, `plyfile` will represent it as an `object`-typed field in the NumPy structured array, where each 'object' is itself a NumPy array (e.g., `('vertex_indices', 'O')`). This means list properties are not automatically flattened into a 2D array upon read, requiring manual post-processing if that's the desired format.

fix

After reading, if a 2D array is needed from a list property, manually concatenate or stack the individual NumPy arrays stored within the `object`-typed field, e.g., `np.vstack(plydata['element_name'].data['list_property'])`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'plyfile'

The 'plyfile' library is not installed in the active Python environment, or the script is being run with a different Python interpreter than where 'plyfile' was installed.

fix

Install the package using pip or conda, ensuring the correct environment is activated: `pip install plyfile` or `conda install -c conda-forge plyfile`.

AttributeError: 'str' object has no attribute 'decode'

This error commonly occurs when reading a binary PLY file where the file object was opened in text mode ('r') instead of binary mode ('rb'), leading to internal parsing issues expecting bytes but receiving strings.

fix

Ensure the PLY file is opened in binary read mode ('rb') when passed to `PlyData.read()`: `with open('file.ply', 'rb') as f: plydata = PlyData.read(f)`.

plyfile.PlyParseError: line X: unexpected characters after 'ply'

This indicates that the PLY file's header is malformed, contains unexpected characters, or has inconsistent line endings immediately following the 'ply' magic word or other header lines.

fix

Verify the PLY file's header for strict adherence to the PLY format specification, checking for extraneous characters, correct format declaration, and consistent Unix-style ('\n') line endings, especially on the 'ply' and 'end_header' lines.

ValueError: all the input arrays must have same number of dimensions

This error occurs when attempting to modify or add properties to an existing `PlyElement.data` NumPy structured array using functions like `numpy.hstack` with arrays that do not match in their fundamental dimensions.

fix

When adding or modifying properties, explicitly create a new structured NumPy array with the desired new fields and copy over the existing data, or use `numpy.lib.recfunctions.merge_arrays` for merging structured arrays.

Upgrade

Version history

1.1.5latest on PyPI · released Jul 28, 2026

Audit

Dependencies

pythonrequiredRequired Python version.

numpyrequiredUnderpins data structures for PLY file representation.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/dranjan/python-plyfile ↗

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

docshttps://python-plyfile.readthedocs.io ↗