Registry / serialization / xattr
library1.3.0pypypi✓ verified 24d ago

xattr is a Python wrapper for extended filesystem attributes, allowing programmatic access to name-data pairs associated with files and directories. It supports listing, getting, setting, and removing these attributes. The library is actively maintained, with several releases per year, and is currently at version 1.3.0.

pip install xattr
INSTALL
IMPORT
SIG · XATTR
X
xattr
serializationpythonv1.3.0
Install
1.9s avg
Import
Disk
18MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.3.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.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.4MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.9s · import 0.000s · 20MB
18MB installed
● package 18MB
Code
Verified usage

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

xattr
import xattr
from xattr import xattr_function
The primary interface is the module itself, acting as a dictionary-like object or providing top-level functions.

This quickstart demonstrates how to set, list, get, and remove extended attributes on a file using `xattr`'s dict-like interface and helper methods. It handles potential `EnvironmentError` if extended attributes are not supported on the system.

import xattr import os # Create a dummy file file_path = "test_file.txt" with open(file_path, "w") as f: f.write("Hello, extended attributes!") try: # Use the dict-like interface to set an attribute file_xattr = xattr.xattr(file_path) file_xattr["user.comment"] = b"This is a test comment" file_xattr["user.tag"] = b"important" print(f"Set 'user.comment' and 'user.tag' on {file_path}") # List all attributes attributes = file_xattr.list() print(f"All attributes: {attributes}") # Get a specific attribute comment = file_xattr.get("user.comment") print(f"'user.comment': {comment.decode('utf-8')}") # Check if an attribute exists if "user.tag" in file_xattr: print(f"'user.tag' exists, value: {file_xattr['user.tag'].decode('utf-8')}") # Remove an attribute file_xattr.remove("user.tag") print("Removed 'user.tag'") attributes_after_removal = file_xattr.list() print(f"Attributes after removal: {attributes_after_removal}") except EnvironmentError as e: print(f"Error accessing extended attributes: {e}") print("Extended attributes may not be supported on this filesystem or OS.") finally: if os.path.exists(file_path): os.remove(file_path) print(f"Cleaned up {file_path}")
Debug
Known issues
breakingPython 3.8 support was dropped in v1.3.0. Python 3.9 or newer is now required. Previous versions (v1.0.0 and above) dropped support for Python 3.7 and older, including Python 2.
fix
Upgrade to Python 3.9 or a newer compatible version, or pin `xattr<1.3.0` for older Python environments.
affects: >=1.3.0
deprecatedThe older functions `listxattr()`, `getxattr()`, `setxattr()`, and `removexattr()` are deprecated since version 0.4. The modern API uses `list()`, `get()`, `set()`, `remove()` or the dict-like interface directly on an `xattr.xattr` object.
fix
Migrate to the newer object-oriented or function-based API (e.g., `x = xattr.xattr(path); x['key'] = value` or `xattr.set(path, 'key', value)`).
affects: All
gotchaExtended filesystem attributes are an OS and filesystem-dependent feature. `xattr` is primarily supported on Linux (kernel 2.6+) and macOS (10.4+), with experimental support for Solaris and FreeBSD. It is generally not supported on Windows.
fix
Ensure your operating system and filesystem support extended attributes. You may encounter `EnvironmentError` or installation failures if not.
affects: All
gotchaOn Linux, custom extended attribute keys *must* be prefixed with a namespace, typically `user.`, (e.g., `user.my_attribute`). Without this prefix, attributes might not be stored or retrieved correctly, or you might encounter permission errors. Other namespaces like `system.`, `security.`, `trusted.` also exist but often require elevated privileges.
fix
Always prepend custom attribute names with `user.` when working on Linux.
affects: All
gotchaWhen reading or writing macOS Spotlight metadata attributes (e.g., Finder comments, `com.apple.metadata:kMDItemFinderComment`), the attribute values are often stored as binary property lists. You will need to use `plistlib.loads()` to decode these values into Python objects.
fix
Import `plistlib` and use `plistlib.loads(value)` to interpret macOS metadata attributes. For more robust macOS metadata handling, consider `osxmetadata`.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'xattr'
The 'xattr' package is not installed in your current Python environment.
fix
pip install xattr
OSError: [Errno 95] Operation not supported
The filesystem or environment (e.g., FAT32, exFAT, some network shares, or specific WSL/Docker setups) does not support extended attributes.
fix
Use a filesystem that supports extended attributes (e.g., ext4, APFS, NTFS) or ensure your environment is configured to allow xattr access (e.g., WSL2 with `mount -o metadata`).
OSError: [Errno 13] Permission denied
The current user lacks the necessary permissions to read or write extended attributes on the specified file or directory.
fix
Run your Python script with elevated privileges (e.g., `sudo python your_script.py`) or adjust the file/directory permissions to grant the current user access.
TypeError: argument 2 must be bytes, not str
The `xattr.set()` method or assigning to an xattr key requires the attribute's value to be a byte string, but a regular Python string was provided.
fix
Encode the string value to bytes before setting it, for example: `xattrs_object['user.myattr'] = 'my_value'.encode('utf-8')`
Upgrade
Version history
1.3.0latest on PyPI · released Oct 13, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
20 hits · last 30 days
node
16
OpenAI (training)
1
Resources
xattr — pip install xattr · libregistry