Install & Compatibility
Where this runs
tested against v0.1.15 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.028s · 19MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.026s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FATFS_Handle
✓ from fatfs import FATFS_Handle
✗ from pyfatfs import PyFatFS
FIL_Handle
✓ from fatfs import FIL_Handle
✗ from pyfatfs import PyFatFS
DIR_Handle
✓ from fatfs import DIR_Handle
✗ from pyfatfs import PyFatFS
This quickstart demonstrates creating a simple in-memory FAT filesystem, writing a file, reading it back, and listing directory contents using the `PyFatBytesIOFS` class from the `pyfatfs` library. This approach is commonly seen in related Python FAT wrappers like `pyfatfs`, as direct `fatfs-ng` specific examples were not readily available under the provided GitHub link.
from pyfatfs import PyFatBytesIOFS
from fs.opener import open_fs
# Create an in-memory FAT12 filesystem image (default size is 1.44MB floppy)
# This uses PyFilesystem2's 'memfs' which is then formatted as FAT
# For fatfs-ng specific usage, it might involve direct class instantiation or a different opener.
# This example is adapted from pyfatfs documentation.
# Initialize a PyFatBytesIOFS for an in-memory FAT filesystem
fat_fs = PyFatBytesIOFS(size=1474560) # 1.44MB floppy size
# Create a file and write to it
with fat_fs.open('test.txt', 'w') as f:
f.write('Hello, fatfs-ng!')
# Read the file
with fat_fs.open('test.txt', 'r') as f:
content = f.read()
print(f"Read from FAT filesystem: {content}")
# List directory contents
print(f"Files in root directory: {fat_fs.listdir('/')}")
# Close the filesystem (important for releasing resources/flushing changes)
fat_fs.close()
# Example using PyFilesystem2 opener with a FAT image (conceptual, actual opener URI might vary)
# with open_fs('fat://my_fat_image.bin') as fat_disk:
# fat_disk.writetext('another_file.txt', 'Content via PyFilesystem2')
# print(fat_disk.listdir('/'))
Debug
Known issues
gotchaThe GitHub repository link provided in the PyPI metadata for 'fatfs-ng' (https://github.com/Jason2866/pyfatfs) appears to point to a user profile 'Jason2866' which does not contain a Python FAT filesystem wrapper. The examples and imports in this registry entry are therefore based on the commonly used 'pyfatfs' library (by nathanhi) which is a prominent Python wrapper for ChaN's FatFS and likely the intended upstream or a very similar project.fixUsers should verify the correct GitHub repository for 'fatfs-ng' if they encounter import errors with 'pyfatfs', or consider using 'pyfatfs' directly if the API is compatible.
affects: All
gotchaWhen manipulating FAT filesystems, especially those intended for embedded systems or specific hardware, ensure correct encoding is used for filenames. FAT typically uses IBM437, but VFAT (long file names) uses UTF-16-LE. Incorrect encoding can lead to unreadable filenames or data corruption.fixExplicitly specify the `encoding` parameter when creating or opening a FAT filesystem if non-standard characters are used or if interoperability with different systems is critical. For VFAT, long file names are typically handled internally as UTF-16-LE.
affects: All
breakingThe underlying ChaN's FatFS C library has undergone various revisions (e.g., R0.15, R0.16) with breaking changes in its C API, especially regarding synchronization functions, argument changes for `f_read`/`f_write`, and `f_mkfs`. While `fatfs-ng` is a Python wrapper, internal updates to the wrapped C library might introduce breaking changes that propagate to the Python API in future major versions.fixAlways review the release notes and migration guides when upgrading `fatfs-ng` to a new major version, as internal changes to the wrapped C library might necessitate Python API adjustments.
affects: Future major versions of fatfs-ng, or significant updates to its wrapped C FatFS version.
gotchaHandling timestamps on FAT filesystems can be tricky. By default, timestamps might be created in local time, which can cause issues with systems expecting UTC.fixConsider using the `utc` parameter (if exposed by `fatfs-ng` or its underlying Python layer, as seen in `pyfatfs`) to create all timestamps in UTC to ensure better interoperability.
affects: All
Upgrade
Version history
0.1.15latest on PyPI · released Jan 20, 2026
Audit
Dependencies
PyFilesystem2optionalOften used for higher-level file system abstraction, though fatfs-ng (and its upstream pyfatfs) can also be used with a low-level API.