pycdlib

library1.20.0pypypi✓ verified 26d ago

PyCdlib is a pure Python library designed to parse, create, and manipulate ISO9660 files, suitable for writing to a CD or USB. It supports various extensions including El Torito, Joliet, Rock Ridge, and UDF. The current stable version available on PyPI is 1.14.0, and it maintains a relatively active development and release cadence.

data serialization database

pip install pycdlib

github ↗package ↗

INSTALL

IMPORT

SIG · PYCDLIB

pycdlib

datapythonv1.20.0

Install

1.7s avg

Import

79ms

Disk

18MB

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.20.0 · 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.080s · 19.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.078s · 20MB

18MB installed

● package 18MB

Code

Verified usage

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

PyCdlib

✓ from pycdlib import PyCdlib

This quickstart demonstrates how to create a new ISO image, add a directory and a file to it, and then write the ISO to a local file. It includes support for Joliet and Rock Ridge extensions during creation and file addition.

from pycdlib import PyCdlib from io import BytesIO import os # Create a new, empty ISO iso = PyCdlib() iso.new(interchange_level=3, joliet=True, rock_ridge='1.09') # Add a directory iso.add_directory('/TESTDIR;1') # Add a file from a BytesIO object file_content = b"Hello, pycdlib!\n" iso.add_fp(BytesIO(file_content), len(file_content), '/TESTFILE.TXT;1', joliet_path='/testfile.txt', rock_ridge_path='testfile.txt') # Define output path (using a temporary file for quickstart example) output_path = 'my_new_iso.iso' # Write the ISO to a file try: iso.write(output_path) print(f"Successfully created ISO image: {output_path}") except Exception as e: print(f"Error creating ISO: {e}") finally: iso.close() # Clean up the created file for the quickstart example if os.path.exists(output_path): # os.remove(output_path) # Uncomment to clean up automatically pass

Debug

Known issues

breakingPython 2.7 compatibility has been removed. PyCdlib versions 1.14.0 and later are strictly Python 3 compatible.

fix

Ensure your project runs on Python 3.x.

affects: <= 1.13.x

gotchaPyCdlib employs a 'lazy' approach to updating ISO metadata for performance. This means that direct inspection of the `PyCdlib` object's internal metadata state might not always reflect the absolute latest changes until `force_consistency()` is explicitly called.

fix

Call `iso.force_consistency()` if you need to ensure all internal metadata is up-to-date before inspection or complex operations.

affects: All versions

gotchaThe library may throw `PyCdlibInvalidISO` or `PyCdlibInternalError` exceptions when encountering ISO files that do not strictly adhere to relevant standards.

fix

For problematic non-standard ISOs, consider reporting an issue to the project's GitHub, ideally with a link to the ISO for analysis.

affects: All versions

gotchaVersion 1.15.0 has been released on GitHub but is not yet available on PyPI (as of current date). Users wishing to access the absolute latest features or fixes must install directly from the GitHub repository rather than via `pip install pycdlib`.

fix

Install from GitHub if 1.15.0+ features are required: `pip install git+https://github.com/clalancette/pycdlib.git`

affects: 1.15.0 (unreleased on PyPI)

Errors

Common errors & fixes

PyCdlibInvalidInput: ISO9660 filenames must consist of characters A-Z, 0-9, and _

The filename or extension provided for an ISO9660 path contains characters not allowed by the strict ISO9660 Level 1 standard, such as lowercase letters, spaces, or most symbols.

fix

Ensure all ISO9660 filenames and extensions use only uppercase letters, numbers, and underscores. For extensions, the format should typically be `/FILENAME.EXT;VERSION`. To use a wider range of characters or longer names, initialize the ISO with Joliet or Rock Ridge extensions, or set a higher `interchange_level` (e.g., `iso.new(joliet=True, rock_ridge='1.09')`).

pycdlib.pycdlibexception.PyCdlibInvalidInput: ISO9660 filenames at interchange level 1 cannot have more than 8 characters or 3 characters in the extension

The filename or its extension exceeds the length limits (8 characters for the name, 3 for the extension) enforced by ISO9660 Level 1.

fix

Shorten filenames and extensions to comply with the 8.3 format (e.g., `MYFILE.TXT`). Alternatively, initialize the ISO with a higher `interchange_level` (e.g., `iso.new(interchange_level=3)`) or enable Joliet/Rock Ridge extensions when creating the ISO to allow for longer filenames.

Error adding files to iso_path with invalid filenames

This often occurs when attempting to add a file via `add_file` or `add_fp` to a path within the ISO where one or more parent directories do not yet exist. Although the specific error message may vary, it indicates a missing directory structure.

fix

Explicitly create all necessary parent directories within the ISO using `iso.add_directory()` before attempting to add files to those paths. The root directory `/` is always present by default.

pycdlib.pycdlibexception.PyCdlibInvalidISO: Valid ISO9660 filesystems must have at least one PVD

pycdlib was used to open an ISO image that does not contain a Primary Volume Descriptor (PVD) as expected by the ISO9660 standard, such as a pure UDF Blu-Ray ISO. pycdlib primarily supports UDF in its 'Bridge' format, which includes an ISO9660 structure.

fix

pycdlib has limited support for UDF-only ISOs; it is designed for UDF 'Bridge' format alongside ISO9660. For UDF-only disks, this library may not be suitable, and an alternative solution or ensuring the ISO is in a compatible 'Bridge' format would be required.

Upgrade

Version history

1.20.0latest on PyPI · released Aug 5, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

37 hits · last 30 days

node

Bingbot

Resources

githubhttp://github.com/clalancette/pycdlib ↗

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