sindresorhus/dsstore

Highlights

• Read & Write: Parse existing files or create new ones from scratch.
• Strongly typed: Type-safe records with DSStore.Record and DSStore.Value.
• Zero dependencies: Pure Swift with no external dependencies.
• Well documented: Comprehensive API documentation and code comments.
• Sendable: Thread-safe types ready for Swift concurrency.

Install

Add the following to Package.swift:

.package(url: "https://github.com/sindresorhus/DSStore", from: "1.0.0")

Or add the package in Xcode.

Usage

Reading a .DS_Store file

import DSStore

let store = try DSStore.read(from: url)

// Get all filenames referenced in the store
print(store.filenames)

// Get all records for a specific file
let records = store.records(for: "README.md")

// Get a specific record
if let position = store.iconPosition(for: "Application.app") {
	print("Icon at: \(position.x), \(position.y)")
}

Creating a .DS_Store file

Perfect for DMG installers with custom icon layouts:

import DSStore

var store = DSStore()

// Set icon positions
try store.setIconPosition(for: "Application.app", x: 140, y: 180)
try store.setIconPosition(for: "Applications", x: 480, y: 180)

// Configure the Finder window
try store.setWindowBounds(top: 100, left: 100, bottom: 400, right: 620)
store.setViewStyle(.iconView)

// Set a background color (each channel is 0-1)
store.setBackground(.color(red: 1, green: 1, blue: 1))

// Write to disk
try store.write(to: url)

Setting a background picture

Finder reads the picture from the icvp record, and the record has to point at the image with a Carbon Alias.

import DSStore

// The folder the store describes, with the image already inside it
let folder = URL(filePath: "/Volumes/MyApp")
let image = folder.appending(path: ".background.png")

var store = DSStore()
try store.setBackgroundPicture(imageURL: image, relativeTo: folder)

try store.write(to: folder.appending(path: ".DS_Store"))

[!IMPORTANT] The image has to be on the volume that the store itself is on, and that volume has to be mounted while you write the store. A Carbon Alias records the volume's identity, including its creation date and file IDs, so an alias made against a build folder, before the volume exists, does not resolve.

So building a DMG takes two steps: make a writable scratch image, mount it, write the store into it, then convert it. This is the same flow dmgbuild and create-dmg use.

# Keep the image inside `src`, so it ends up inside the volume.
hdiutil create -srcfolder ./src -format UDRW -volname MyApp scratch.dmg
hdiutil attach scratch.dmg

# Write the store to /Volumes/MyApp/.DS_Store here, the way the Swift
# example above does, while the volume is mounted.

hdiutil detach /Volumes/MyApp
hdiutil convert scratch.dmg -format UDZO -o MyApp.dmg

If you already have Carbon Alias data for the image, use setBackgroundPicture(aliasData:) instead. Finder does not accept bookmark data there, not even data from URL.bookmarkData(options: .suitableForBookmarkFile, relativeTo:).

Working with records directly

import DSStore

var store = DSStore()

// Add a Spotlight comment
store.add(DSStore.Record(
	filename: "Important.txt",
	type: .spotlightComment,
	value: .string("Don't delete this file!")
))

// Add a custom blob record
store.add(DSStore.Record(
	filename: ".",
	type: .custom(.literal("icvp")),
	value: .data(plistData)
))

// Remove records
store.removeRecords(for: "OldFile.txt")

API

See the API docs.

FAQ

What is a .DS_Store file?

.DS_Store (Desktop Services Store) is a hidden file created by macOS Finder in every folder it opens. It stores custom attributes like icon positions, view settings, and folder backgrounds.

Why would I need to parse or create these files?

The most common use case is creating DMG installers with custom layouts — positioning the app icon and Applications folder alias in specific locations with a nice background image.

Is the file format documented by Apple?

No, it's a proprietary format. This library is based on reverse-engineering work by Mark Mentovai, Wim Lewis, and others.

Does this work on Linux?

The parsing and writing work anywhere Swift runs, but .DS_Store files are only used by macOS Finder.

Can I use this to clean up .DS_Store files?

Yes! You can read a file, inspect its contents, remove entries, and write it back. Or just delete the file entirely — Finder will recreate it.

Why did you make this?

I just wanted to work around an old macOS bug.

Package Metadata

Repository: sindresorhus/dsstore

Default branch: main

README: readme.md