ds-store

1.3.2 verified Mon Apr 27 auth: no python

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.

pip install ds-store

Common errors

error ds_store is not installed ↓

cause The package name on PyPI uses a hyphen, but some tutorials mistakenly import 'dsstore' without hyphen.

fix

Install with pip install ds-store and import with from ds_store import DSStore.

error ModuleNotFoundError: No module named 'dsstore' ↓

cause Attempted to import with the PyPI package name (hyphen) as the module name.

fix

Use from ds_store import DSStore (underscore, not hyphen).

error AttributeError: module 'ds_store' has no attribute 'DSStore' ↓

cause In very old versions (<1.0) the class name was different, or there may be a dependency conflict with another library.

fix

Upgrade to latest version: pip install --upgrade ds-store.

Warnings

gotcha DSStore.open() returns a context manager that must be used with 'with'. Forgetting to close can leave the file in an inconsistent state. ↓

fix Always use `with DSStore.open(path, mode) as d:`.

breaking 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. ↓

fix Use `from ds_store import DSStore` (the preferred public API) or explicitly `from ds_store.dsstore import DSStore` if needed.

deprecated The `DSStoreEntry` class is deprecated in favor of accessing entry data via the `DSStore` iterator directly. Instantiating `DSStoreEntry` manually is no longer supported. ↓

fix Iterate over `DSStore` object or use `d[key]` syntax; do not create `DSStoreEntry` directly.

gotcha 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. ↓

fix Refer to the source code for exact binary formats or use higher-level helpers (e.g., `DSStoreEntry.set_icon_position` if available).

Imports

DSStore
wrong
```
from dsstore import DSStore
```
correct
```
from ds_store import DSStore
```
The package name uses a hyphen in PyPI but the module name is ds_store with an underscore.

Quickstart

Open a .DS_Store file, iterate over entries, and create a new file with custom icon positions and view settings.

from ds_store import DSStore

# Open an existing .DS_Store file
with DSStore.open('/Users/me/.DS_Store', 'r+') as d:
    # Print all entries
    for entry in d:
        print(entry.filename, entry.type, entry.code, entry.data)

# Create a new .DS_Store file
with DSStore.open('new.DS_Store', 'w+') as d:
    d['MyFolder'] = {
        'Iloc': (100, 100),
        'icvp': {'showIconPreview': True},
        'extd': {'extended_data': b'...'},
    }