モジュール統合の全体像

nix-darwin上でユーザー環境を宣言的に管理する場合、独立したHome Manager実行ではなく、darwin-configuration.nixから直接モジュールを呼び出すアプローチが推奨される。この方式ではシステム構築とユーザー環境の構築が単一の評估サイクルで完結し、一貫性と再現性が向上する。

セットアップ手順

Flakesを使わない場合のチャネル登録

従来のチャネルベース運用では、nix-darwinのチャネルに合わせてHome Managerのチャネルも固定する。

# nixpkgs unstable追従時
nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz hm
nix-channel --update hm

# 25.05系追従時
nix-channel --add https://github.com/nix-community/home-manager/archive/release-25.05.tar.gz hm
nix-channel --update hm

Flakes対応推奨設定

現代的な構成ではflake.nix内で直接入力を宣言する。

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
    darwin = {
      url = "github:LnL7/nix-darwin";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    home-manager = {
      url = "github:nix-community/home-manager";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, darwin, home-manager, ... }@attrs:
    let
      hostParams = { system = "aarch64-darwin"; pkgs = nixpkgs.legacyPackages.aarch64-darwin; };
    in
    {
      darwinConfigurations.workstation = darwin.lib.darwinSystem {
        inherit (hostParams) system pkgs;
        modules = [
          home-manager.darwinModules.home-manager
          ./hosts/workstation/default.nix
        ];
      };
    };
}

実用的な構成パターン

単一ユーザー構成

最もシンプルな形態。ユーザーaliceの環境を構築する例。

{ pkgs, ... }:

{
  users.knownUsers = [ "alice" ];
  users.users.alice = {
    uid = 501;
    home = "/Users/alice";
    shell = pkgs.zsh;
  };

  home-manager = {
    useGlobalPkgs = true;
    useUserPackages = true;
    
    users.alice = { config, lib, ... }: {
      imports = [ ./modules/shell ./modules/devtools ];
      
      home = {
        username = "alice";
        homeDirectory = lib.mkForce "/Users/alice";
        stateVersion = "25.05";
      };

      programs.git = {
        enable = true;
        userName = "Alice";
        userEmail = "alice@example.com";
      };
    };
  };
}

複数ユーザー・マシン別設定

複数ホストを管理する場合、ユーザーごとの共通設定とマシン固有設定を分離する。

# hosts/mbp2023/default.nix
{ config, lib, ... }:

{
  imports = [
    ../../users/alice
    ../../users/shared/macos-defaults
  ];

  home-manager.users.alice = {
    home.packages = with pkgs; [
      raycast
      orbstack
    ];
    
    # マシン固有の環境変数
    home.sessionVariables = {
      MACHINE_NAME = "mbp2023";
    };
  };
}

主要オプションの挙動

オプション	効果	推奨設定
useGlobalPkgs	システムと同一のnixpkgsインスタンスを使用	true（重複評估回避）
useUserPackages	パッケージを/etc/profiles/per-user/配下に配置	true（PATH競合防止）
backupFileExtension	衝突時の既存ファイルバックアップ拡張子	"backup"等を指定

セッション変数の取り扱い

Home Manager管理外のシェル（macOS標準の.zshrc等を手動編集している場合）で環境変数を有効化するには、以下のいずれかを.zshrcに追加する。

# useUserPackages = true の場合
source /etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh

# useUserPackages = false（デフォルト）の場合
source $HOME/.nix-profile/etc/profile.d/hm-session-vars.sh

osConfigによるシステム連携

Home Managerモジュール内でosConfigパラメータを受け取ることで、nix-darwin側の設定値を参照できる。

{ config, lib, pkgs, osConfig, ... }:

let
  # システムレベルのホスト名を利用
  hostname = osConfig.networking.hostName;
in
{
  programs.zsh.initExtra = ''
    # プロンプトにホスト名を反映
    PROMPT="%m ${hostname} %~ %# "
  '';
  
  # システムパッケージの有無で条件分岐
  home.packages = lib.optional osConfig.programs.fish.enable pkgs.fishPlugins.done;
}

トラブルシューティング

パーミッションエラー

useUserPackages = true時に/nix/store関連の書き込みエラーが発生する場合、nix-darwinのビルドユーザ設定を確認する。

nix.settings.build-users-group = "nixbld";

アプリケーションバンドルの検出

GUIアプリケーションがLaunchpadに表示されない場合、home.packagesではなくhomebrew.casksとの併用を検討するか、以下のようにhome.activationでリンクを作成する。

home.activation.linkApplications = lib.hm.dag.entryAfter [ "writeBoundary" ] ''
  if [ -d ~/Applications/Home\ Manager\ Apps ]; then
    ln -sf ~/Applications/Home\ Manager\ Apps/*.app ~/Applications/ 2>/dev/null || true
  fi
'';

設定検証ワークフロー

変更を適用する前に必ずビルドテストを実行する。

# ビルドのみ実行（適用しない）
darwin-rebuild build --flake .#workstation

# 即時適用
darwin-rebuild switch --flake .#workstation

# 特定ユーザーのHome Managerのみ再構築
home-manager switch --flake .#alice

なお、home-managerコマンドを単独で使用する場合はhome-manager.useUserPackagesとパッージパスが一致するよう注意が必要である。