{"id":26915,"library":"ds-store","title":"ds-store","description":"A Python library for reading and writing .DS_Store files (the metadata files created by Apple's Finder) and exploring the file system metadata they contain. Current version is 1.3.2, released in 2023; development is active on GitHub with minimal release cadence.","status":"active","version":"1.3.2","language":"python","source_language":"en","source_url":"https://github.com/dmgbuild/ds_store","tags":["ds_store","finder","macos","metadata","apple"],"install":[{"cmd":"pip install ds-store","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"For handling alias/bookmark records within DS_Store files","package":"mac_alias","optional":false},{"reason":"For parsing binary property lists inside DS_Store entries","package":"biplist","optional":false}],"imports":[{"note":"The package name uses a hyphen in PyPI but the module name is ds_store with an underscore.","wrong":"from dsstore import DSStore","symbol":"DSStore","correct":"from ds_store import DSStore"}],"quickstart":{"code":"from ds_store import DSStore\n\n# Open an existing .DS_Store file\nwith DSStore.open('/Users/me/.DS_Store', 'r+') as d:\n    # Print all entries\n    for entry in d:\n        print(entry.filename, entry.type, entry.code, entry.data)\n\n# Create a new .DS_Store file\nwith DSStore.open('new.DS_Store', 'w+') as d:\n    d['MyFolder'] = {\n        'Iloc': (100, 100),\n        'icvp': {'showIconPreview': True},\n        'extd': {'extended_data': b'...'},\n    }","lang":"python","description":"Open a .DS_Store file, iterate over entries, and create a new file with custom icon positions and view settings."},"warnings":[{"fix":"Always use `with DSStore.open(path, mode) as d:`.","message":"DSStore.open() returns a context manager that must be used with 'with'. Forgetting to close can leave the file in an inconsistent state.","severity":"gotcha","affected_versions":"all"},{"fix":"Use `from ds_store import DSStore` (the preferred public API) or explicitly `from ds_store.dsstore import DSStore` if needed.","message":"In version 1.3.0, the DSStore class was moved from the top-level `ds_store` module to `ds_store.dsstore`. Old imports like `from ds_store import DSStore` still work via a compatibility alias, but direct `from ds_store.dsstore import DSStore` may be required in some edge cases.","severity":"breaking","affected_versions":">=1.3.0"},{"fix":"Iterate over `DSStore` object or use `d[key]` syntax; do not create `DSStoreEntry` directly.","message":"The `DSStoreEntry` class is deprecated in favor of accessing entry data via the `DSStore` iterator directly. Instantiating `DSStoreEntry` manually is no longer supported.","severity":"deprecated","affected_versions":">=1.3.0"},{"fix":"Refer to the source code for exact binary formats or use higher-level helpers (e.g., `DSStoreEntry.set_icon_position` if available).","message":"Setting custom metadata values (like 'Iloc' or 'icvp') requires exact byte-level formatting. Incorrect data can corrupt the file or cause Finder to ignore entries.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Install with `pip install ds-store` and import with `from ds_store import DSStore`.","cause":"The package name on PyPI uses a hyphen, but some tutorials mistakenly import 'dsstore' without hyphen.","error":"ds_store is not installed"},{"fix":"Use `from ds_store import DSStore` (underscore, not hyphen).","cause":"Attempted to import with the PyPI package name (hyphen) as the module name.","error":"ModuleNotFoundError: No module named 'dsstore'"},{"fix":"Upgrade to latest version: `pip install --upgrade ds-store`.","cause":"In very old versions (<1.0) the class name was different, or there may be a dependency conflict with another library.","error":"AttributeError: module 'ds_store' has no attribute 'DSStore'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}