---
id: ds-store
version: "1.3.3"
license: MIT
license_treatment: permissive
maintenance: active
---

# ds-store — Manipulate Finder .DS_Store files from Python

License: permissive · Maintenance: active · Downloads: 211.1K/mo

## What it is and what it does

ds_store is a pure-Python library for reading and modifying macOS Finder .DS_Store files, the hidden metadata files that store folder view settings and file attributes on macOS. Because it's written in pure Python rather than as a native macOS tool, it runs on any platform—Linux, Windows, or macOS—making it useful for build systems, disk image creation, and cross-platform tooling that needs to inspect or manipulate these files without running on a Mac.

The package wraps the binary .DS_Store format (reverse-engineered from public documentation) and exposes it through a Python API. It depends only on mac_alias, another pure-Python library for handling macOS alias records, keeping the dependency chain minimal and portable.

Use it for:

- Examine .DS_Store metadata in disk images or macOS filesystem backups on non-Mac systems
- Automate creation of DMG files with specific Finder view settings during cross-platform build processes
- Parse Finder folder attributes and custom icon positions from .DS_Store files in CI/CD pipelines
- Modify .DS_Store files to reset view preferences or clean up metadata in batch operations

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Read and modify macOS Finder .DS_Store files from Python code on any platform, without requiring macOS.

Yes, if you need to read or modify .DS_Store files outside macOS. Low install friction, no known vulnerabilities, MIT-licensed, actively maintained, and production-stable. The narrow use case (macOS filesystem metadata on non-Mac platforms) makes it essential for its niche but not generally useful otherwise.

## Install

pip install ds-store
uv add ds-store
poetry add ds-store

## Installing ds-store

Before you install: Low install friction with a single pure-Python dependency (mac_alias). Actively maintained with recent commits and production-stable status.

License in practice: MIT license permits commercial and private use with minimal restrictions.

Quickstart:

pip install ds-store

from ds_store import DSStore

with DSStore.open('path/to/.DS_Store') as ds:
    for entry in ds:
        print(entry.filename)

Verify before relying:

- Specific API surface for modifying .DS_Store entries beyond reading them
- Performance characteristics when handling large or complex .DS_Store files
- Compatibility guarantees with different macOS versions' .DS_Store format variants

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 211.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

ds_store file manipulation, read ds_store python, modify finder metadata, macos ds_store parser, .ds_store editor, cross-platform ds_store, finder file attributes python, macos-interop, file-format-parser

[View on SkillFed](https://skillfed.io/packages/ds-store) · [View on PyPI](https://pypi.org/project/ds-store/)