Table Of Contents

Introduction

Plist-manager (PM) is a Nix module for managing macOS user defaults. Unlike the built-in options offered by nix-darwin and home-manager, PM provides the following advantages:

  • Human-friendly naming of domains and options, e.g., trackpad.draggingStyle = "three-fingers".
  • Automatic reloading of system settings with activateSettings -u after applying changes.
  • Unsetting an option or explicitly setting it to null resets its value, effectively performing a defaults delete <domain> <option> command.

The null equals reset rule makes this module particularly useful, as it ensures that any option previously set is restored to the system default. This behavior is crucial for configurations that are conditionally set, e.g., NSGlobalDomain.AppleInterfaceStyle, which is removed if the user opts for Light or Auto appearance mode.

important

Since all options provided by this module default to null, by adding the module to a Nix flake you risk losing some user defaults that are not managed with Nix.

This also makes the module incompatible with the built-in alternatives from nix-darwin and home-manager (unless used to set values that aren't touched by plist-manager; see the "Affects: ..." block next to each option in the reference for more information about which plist keys are affected).

In the near future, I plan to keep track of unset values properly and only delete those instead of every attribute.

Installation

To get started, add plist-manager to your Nix flake inputs:

{
  inputs.plist-manager.url = "github:z0al/plist-manager";
  inputs.plist-manager.inputs.nixpkgs.follows = "nixpkgs";
}

This module provides integrations for both nix-darwin and home-manager. You can use either one, but NOT both, to avoid behavior conflicts.

For nix-darwin users

Add plist-manager.darwinModules.default to your nix-darwin modules:

{
	darwinConfigurations.hostname = darwin.lib.darwinSystem {
    modules = [
      # ... other modules
      plist-manager.darwinModules.default
    ];
  };
}

For home-manager users

Add plist-manager.homeManagerModules.default to your home-manager modules:

{
	homeConfigurations.userName = home-manager.lib.homeManagerConfiguration {
    modules = [
      # ... other modules
      plist-manager.homeManagerModules.default
    ];
  };
}

Reference

Below is a list of available options, grouped by category. Each option declares the underlying system properties it modifies under "Affects", which can be useful for searching if you already know that information or for debugging.

If an option you need is missing, please feel free to open a pull request.

Appearance

plist.appearance.showScrollBar

Control when the scroll bar is shown

Affects:

  • “NSGlobalDomain”.“AppleShowScrollBars”

Type: null or one of “auto”, “always”, “when-scrolling”

Default: null

Declared by:

plist.appearance.theme

Choose the appearance for buttons, menus and windows.

Note that auto won’t switch the appearance until your device has been idle for at least a minute or if an app is preventing the display from sleeping, such as during media playback

Affects:

  • “NSGlobalDomain”.“AppleInterfaceStyle”
  • “NSGlobalDomain”.“AppleInterfaceStyleSwitchesAutomatically”

Type: null or one of “auto”, “light”, “dark”

Default: null

Declared by:

Desktop

plist.desktop.keepFoldersOnTop

Whether to keep folders on top when sorting

Affects:

  • “com.apple.finder”.“_FXSortFoldersFirstOnDesktop”

Type: null or boolean

Default: null

Declared by:

plist.desktop.showConnectedServers

Whether to show connected servers on the desktop

Affects:

  • “com.apple.finder”.“ShowMountedServersOnDesktop”

Type: null or boolean

Default: null

Declared by:

plist.desktop.showExternalDisks

Whether to show external disks on the desktop

Affects:

  • “com.apple.finder”.“ShowExternalHardDrivesOnDesktop”

Type: null or boolean

Default: null

Declared by:

plist.desktop.showHardDisks

Whether to show hard disks on the desktop

Affects:

  • “com.apple.finder”.“ShowHardDrivesOnDesktop”

Type: null or boolean

Default: null

Declared by:

plist.desktop.showIcons

Whether to show icons on the desktop

Affects:

  • “com.apple.finder”.“CreateDesktop”

Type: null or boolean

Default: null

Declared by:

plist.desktop.showRemovableMedia

Whether to show removable media (CDs, DVDs and iPods) on the desktop

Affects:

  • “com.apple.finder”.“ShowRemovableMediaOnDesktop”

Type: null or boolean

Default: null

Declared by:

Dock

plist.dock.autoHide.enable

Whether to automatically hide and show the dock

Affects:

  • “com.apple.dock”.“autohide”

Type: null or boolean

Default: null

Declared by:

plist.dock.autoHide.animationDelay

Sets the speed of the animation when hiding/showing the Dock

Affects:

  • “com.apple.dock”.“autohide-time-modifier”

Type: null or floating point number

Default: null

Declared by:

plist.dock.autoHide.delay

Sets the speed of the auto-hide delay

Affects:

  • “com.apple.dock”.“autohide-delay”

Type: null or floating point number

Default: null

Declared by:

plist.dock.minimize.effect

Sets the effect of minimizing windows

Affects:

  • “com.apple.dock”.“mineffect”

Type: null or one of “genie”, “scale”, “suck”

Default: null

Declared by:

plist.dock.minimize.toApplicationIcon

Whether to minimize windows to the application icon

Affects:

  • “com.apple.dock”.“minimize-to-application”

Type: null or boolean

Default: null

Declared by:

plist.dock.position

Position of the dock on screen

Affects:

  • “com.apple.dock”.“orientation”

Type: null or one of “bottom”, “left”, “right”

Default: null

Declared by:

plist.dock.showRecentApps

Whether to show recent applications in the Dock

Affects:

  • “com.apple.dock”.“show-recents”

Type: null or boolean

Default: null

Declared by:

plist.dock.size

Size of the dock icons

Affects:

  • “com.apple.dock”.“tilesize”

Type: null or signed integer

Default: null

Declared by:

Finder

plist.finder.keepFoldersOnTop

Whether to keep folders on top when sorting

Affects:

  • “com.apple.finder”.“_FXSortFoldersFirst”

Type: null or boolean

Default: null

Declared by:

plist.finder.showExtensions

Whether to show file extensions in the Finder

Affects:

  • “NSGlobalDomain”.“AppleShowAllExtensions”

Type: null or boolean

Default: null

Declared by:

plist.finder.showHidden

Whether to show hidden files in Finder

Affects:

  • “com.apple.finder”.“AppleShowAllFiles”

Type: null or boolean

Default: null

Declared by:

Safari

plist.safari.devTools.enable

Whether to enable the developer tools in Safari

Affects:

  • “com.apple.Safari.SandboxBroker”.“ShowDevelopMenu”

Type: null or boolean

Default: null

Declared by:

Trackpad

plist.trackpad.draggingStyle

Adjust the trackpad dragging style:

  • Double Tap: Double-tap an item to drag with lifting your fingers. Dragging continues if you briefly lift your fingers; otherwise, it stops.
  • Double Tap Lock: Double-tap an item to drag without lifting your fingers. Dragging continues even after you lift your fingers until you tap once again.
  • Three Fingers: Drag an item with three fingers. Dragging continues if you briefly lift your fingers; otherwise, it stops.

Affects:

  • “com.apple.AppleMultitouchTrackpad”.“DragLock”
  • “com.apple.AppleMultitouchTrackpad”.“Dragging”
  • “com.apple.AppleMultitouchTrackpad”.“TrackpadThreeFingerDrag”
  • “com.apple.driver.AppleBluetoothMultitouch.trackpad”.“DragLock”
  • “com.apple.driver.AppleBluetoothMultitouch.trackpad”.“Dragging”
  • “com.apple.driver.AppleBluetoothMultitouch.trackpad”.“TrackpadThreeFingerDrag”

Type: null or one of “double-tap”, “double-tap-lock”, “three-fingers”

Default: null

Declared by:

plist.trackpad.naturalScrolling

Whether to move the contents of a window in the same direction as your fingers

Affects:

  • “NSGlobalDomain”.“com.apple.swipescrolldirection”

Type: null or boolean

Default: null

Declared by:

plist.trackpad.speed

Adjust the trackpad tracking speed

Affects:

  • “NSGlobalDomain”.“com.apple.trackpad.scaling”

Type: null or integer or floating point number between 0 and 3 (both inclusive)

Default: null

Declared by:

plist.trackpad.tapToClick

Whether to enable tap to click

Affects:

  • “com.apple.AppleMultitouchTrackpad”.“Clicking”
  • “com.apple.driver.AppleBluetoothMultitouch.trackpad”.“Clicking”

Type: null or boolean

Default: null

Declared by:

License

This project is licensed under the terms of the MIT license.