{"id":3856,"library":"xattr","title":"xattr: Extended Filesystem Attributes","description":"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.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/xattr/xattr","tags":["filesystem","attributes","metadata","os-specific","linux","macos"],"install":[{"cmd":"pip install xattr","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The primary interface is the module itself, acting as a dictionary-like object or providing top-level functions.","wrong":"from xattr import xattr_function","symbol":"xattr","correct":"import xattr"}],"quickstart":{"code":"import xattr\nimport os\n\n# Create a dummy file\nfile_path = \"test_file.txt\"\nwith open(file_path, \"w\") as f:\n    f.write(\"Hello, extended attributes!\")\n\ntry:\n    # Use the dict-like interface to set an attribute\n    file_xattr = xattr.xattr(file_path)\n    file_xattr[\"user.comment\"] = b\"This is a test comment\"\n    file_xattr[\"user.tag\"] = b\"important\"\n\n    print(f\"Set 'user.comment' and 'user.tag' on {file_path}\")\n\n    # List all attributes\n    attributes = file_xattr.list()\n    print(f\"All attributes: {attributes}\")\n\n    # Get a specific attribute\n    comment = file_xattr.get(\"user.comment\")\n    print(f\"'user.comment': {comment.decode('utf-8')}\")\n\n    # Check if an attribute exists\n    if \"user.tag\" in file_xattr:\n        print(f\"'user.tag' exists, value: {file_xattr['user.tag'].decode('utf-8')}\")\n\n    # Remove an attribute\n    file_xattr.remove(\"user.tag\")\n    print(\"Removed 'user.tag'\")\n\n    attributes_after_removal = file_xattr.list()\n    print(f\"Attributes after removal: {attributes_after_removal}\")\n\nexcept EnvironmentError as e:\n    print(f\"Error accessing extended attributes: {e}\")\n    print(\"Extended attributes may not be supported on this filesystem or OS.\")\nfinally:\n    if os.path.exists(file_path):\n        os.remove(file_path)\n        print(f\"Cleaned up {file_path}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to Python 3.9 or a newer compatible version, or pin `xattr<1.3.0` for older Python environments.","message":"Python 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.","severity":"breaking","affected_versions":">=1.3.0"},{"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)`).","message":"The 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.","severity":"deprecated","affected_versions":"All"},{"fix":"Ensure your operating system and filesystem support extended attributes. You may encounter `EnvironmentError` or installation failures if not.","message":"Extended 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Always prepend custom attribute names with `user.` when working on Linux.","message":"On 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Import `plistlib` and use `plistlib.loads(value)` to interpret macOS metadata attributes. For more robust macOS metadata handling, consider `osxmetadata`.","message":"When 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}