ds-store

library1.3.2pypypi✓ verified 90d ago

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.

serialization data

pip install ds-store

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · DS-STORE

ds-store

serializationpythonv1.3.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

DSStore

✓ from ds_store import DSStore

✗ from dsstore import DSStore

The package name uses a hyphen in PyPI but the module name is ds_store with an underscore.

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'...'}, }

Debug

Known issues

gotchaDSStore.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:`.

affects: all

breakingIn 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.

affects: >=1.3.0

deprecatedThe `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.

affects: >=1.3.0

gotchaSetting 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).

affects: all

Errors

Common errors & fixes

ds_store is not installed

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`.

ModuleNotFoundError: No module named 'dsstore'

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

fix

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

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

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`.

Upgrade

Version history

1.3.2latest on PyPI · released Dec 4, 2025

Audit

Dependencies

mac_aliasrequiredFor handling alias/bookmark records within DS_Store files

biplistrequiredFor parsing binary property lists inside DS_Store entries

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dmgbuild/ds_store ↗

packagehttps://pypi.org/project/ds-store/ ↗

docshttps://ds-store.readthedocs.io/en/latest/ ↗