macdefault 0.2.1

A macOS command-line utility for switching default file associations by file extension

macdefault

A macOS command-line utility for switching default file associations by file extension.

Overview

macdefault manages default application associations for common office document formats using macOS's duti utility. Switch entire office suites with a single command instead of manually changing file associations through Finder.

Supported file extensions:

• Word: doc, docx
• Excel: xls, xlsx
• PowerPoint: ppt, pptx
• Other: rtf, csv

Supported application suites:

• Microsoft Office - Word, Excel, PowerPoint
• WPS Office - Single application (Kingsoft)
• Apple iWork - Pages, Numbers, Keynote, TextEdit

Requirements

• macOS only (uses LaunchServices and duti)
• Python 3.10+
• duti - Install via: brew install duti
• uv - Python package manager (installation)
• Python deps - Installed automatically by uv (click, questionary, wcwidth)

Installation

Quick Start with uv

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install duti
brew install duti

# Run directly without installation
uv run macdefault --help

Install as a Tool

# Install globally with uv
uv tool install .

# Now you can run it anywhere
macdefault --help

Development Setup

# Clone the repository
git clone https://github.com/ac1982/macdefault.git
cd macdefault

# uv will automatically create a virtual environment and install dependencies
uv sync

# Run in development mode
uv run macdefault --help

Usage

Switch to a Suite

Switch all supported file types to Microsoft Office:

uv run macdefault --microsoft
# or
uv run macdefault --office

Switch to WPS Office:

uv run macdefault --wps
# or
uv run macdefault --kingsoft

Switch to Apple iWork suite:

uv run macdefault --apple

Interactive Mode

Choose a default app for a specific extension:

uv run macdefault --ext=doc

This will:

1. Show the current default handler
2. List all installed apps that support .doc files
3. Let you select one from the list using Up/Down arrows or by typing a number (1-9), press q to cancel
4. Apply the changes

Show candidates without making changes:

uv run macdefault --ext=doc --show

Diagnostics

Print a summary of installed office suites:

uv run macdefault --print-bundle-ids

Full diagnostic output (bundle IDs + current defaults):

uv run macdefault --doctor

This shows:

• Which office apps are installed
• Their bundle IDs and paths
• Current default handlers for all managed extensions

Additional Options

Dry run (preview changes without applying):

uv run macdefault --microsoft --dry-run

Disable verification (skip checking if changes succeeded):

uv run macdefault --wps --no-verify

Fail fast (stop on first error):

uv run macdefault --apple --fail-fast

How It Works

1. Discovery: Scans common application directories (/Applications, etc.) for installed apps
2. UTI Matching: Uses macOS Uniform Type Identifiers to find apps that support each file extension
3. LaunchServices: Registers apps with lsregister when needed
4. duti: Applies the default handler settings via duti -s <bundle-id> <extension> all
5. Verification: Checks that changes were applied correctly

Special Handling

• WPS Office: Uses a stable path (/Applications/wpsoffice.app) since LaunchServices name lookup can be unreliable
• Microsoft Word .doc files: Includes automatic repair logic if the default doesn't stick, re-registering with LaunchServices and applying multiple UTI variants

Examples

Typical Workflow

Check what's currently set:

uv run macdefault --doctor

Switch to Microsoft Office:

uv run macdefault --microsoft

Verify the changes:

uv run macdefault --doctor

Choose Custom Handler for One Extension

Set a different app for .md files:

uv run macdefault --ext=md

See what handles .csv without changing:

uv run macdefault --ext=csv --show

Troubleshooting

"duti not found"

• Install via: brew install duti

"Microsoft Office apps not fully resolvable"

• Ensure Word, Excel, and PowerPoint are installed in /Applications
• Try running uv run macdefault --print-bundle-ids to see what's detected

Changes don't stick for .doc files

• The script includes automatic repair logic for this common issue
• It re-registers Word with LaunchServices and tries multiple UTI identifiers

App not appearing in --ext list

• The app must declare support for that file type in its Info.plist
• As a workaround, use Finder: right-click file → Open With → Other → Change All

Project Structure

macdefault/
├── macdefault.py       # Main script
├── pyproject.toml      # Project metadata and dependencies
├── README.md           # This file
├── .python-version     # Python version specification
└── .gitignore          # Git ignore rules

Development

Running Tests

# Add tests in the future
uv run pytest

Code Formatting

# Add formatters as dev dependencies if needed
uv add --dev ruff black
uv run black macdefault.py
uv run ruff check macdefault.py

Technical Details

• Uses mdls for fast metadata queries when available
• Falls back to parsing Info.plist directly
• Filters out overly-generic UTIs (public.data, public.item, public.content)
• Supports wide Unicode characters in table output via wcwidth
• Interactive mode supports ESC to cancel (when running in a TTY)

License

MIT License - See LICENSE file for details.