nix claude code｜NixOSの導入・更新・Home Manager設定

nix claude codeとは？NixOSでの位置づけ

検索キーワードの「nix claude code」は、単一の公式コマンド名ではありません。一般には、NixOSやNixパッケージ管理で、ターミナルから使うClaude Codeを導入したいという意味で使われます。Claude Code本体は、プロジェクトのファイルを読み、質問への回答や編集、テスト実行などを行うCLIです。Nixは、その実行ファイルと依存関係を宣言的に管理します。

ここで、似ている3つの選択肢を分けて考えると迷いません。

Claude Code公式のセットアップページで明記されている対応環境はmacOS、Windows、Ubuntu、Debian、Alpineなどで、NixOSは一覧に含まれていません。したがってNixOSでは、配布元のスクリプトを直接実行するより、Nix側でパッケージ化されたルートを選ぶほうが、依存関係と更新方法をそろえやすくなります。

出典: https://code.claude.com/docs/en/installation

まずnixpkgsのClaude Codeを導入する手順

NixOSの構成ファイルで管理するなら、最初に試す候補はpkgs.claude-codeです。現在のnixpkgsの定義はAnthropicの配布サーバーからネイティブバイナリを取得し、Linux向けに必要なライブラリや検索・サンドボックス用の実行ファイルをラッパー側で用意します。

1. 利用中のチャンネルにパッケージがあるか確認します。

   nix search nixpkgs claude-code
   

2. configuration.nixに、unfreeパッケージの許可とシステムへの追加を記述します。

   { pkgs, lib, ... }:
   {
     nixpkgs.config.allowUnfreePredicate = pkg:
       builtins.elem (lib.getName pkg) [ "claude-code" ];
   
     environment.systemPackages = [
       pkgs.claude-code
     ];
   }
   

3. 設定を反映します。

   sudo nixos-rebuild switch
   

4. バージョン表示と診断を実行し、問題がなければプロジェクトディレクトリでclaudeを起動します。

   claude --version
   claude doctor
   claude
   

allowUnfree = trueでも動かせますが、許可範囲がすべてのunfreeパッケージに広がります。Claude Codeだけを対象にするなら、上のallowUnfreePredicateのほうが意図を明確にできます。なお、古い解説で見かけるclaude-code-binは、現在のnixpkgsではclaude-codeへ統合された案内があるため、コピーペーストする前に属性名を確認してください。

出典: https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/cl/claude-code/package.nix

出典: https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/aliases.nix

Home Managerでユーザー設定まで管理する

システム全体に入れる必要がなく、ログインユーザーごとにClaude Codeを整えたいなら、Home Managerが扱いやすい選択肢です。公式マニュアルにはprograms.claude-code.enable、package、settings、contextなどの項目があり、実行ファイルだけでなく設定ファイルも宣言できます。標準の設定ディレクトリは~/.claudeです。

1. Home Managerのユーザーモジュールでprograms.claude-codeを有効にします。

   {
     programs.claude-code = {
       enable = true;
       package = pkgs.claude-code;
   
       context = ''
         このプロジェクトでは変更前にテストを実行する。
       '';
   
       settings = {
         permissions = {
           deny = [
             "Read(./.env)"
             "Read(./secrets/**)"
           ];
         };
       };
     };
   }
   

2. Home Managerをflakeで使っている場合は、pkgsを作る段階でclaude-codeのunfree許可を設定します。NixOSのモジュールに組み込んでいる場合も、同じ許可がそのパッケージ評価に届いているか確認します。

3. home-manager switch --flake .#ユーザー名を実行し、シェルを開き直してcommand -v claudeとclaude --versionを確認します。

contextは全体の前提をCLAUDE.mdとして配置し、settingsはsettings.jsonへ反映されます。秘密情報をプロジェクト内へ置かず、読み取り拒否のパターンを先に宣言しておくと、設定を別のマシンへ移しても安全側の初期状態を再現できます。

出典: https://nix-community.github.io/home-manager/options/home-manager/programs/claude-code.html

nix-claude-code flakeを使う場合の手順

検索結果で見かけるnix-claude-codeは、Anthropicの公式配布サーバーからClaude Codeのバイナリを取得するコミュニティ製flakeです。Linuxのx86_64・aarch64だけでなくmacOSにも対応し、SHA-256チェックサムの検証、stableとlatestのチャンネル、特定バージョンの指定に対応しています。nixpkgsの更新を待たず、リリースを早く試したい人に向きます。

まず、インストールせずに動作を確かめるなら次の形です。unfreeパッケージの評価を環境変数で許可するため、--impureも付けています。

NIXPKGS_ALLOW_UNFREE=1 nix run --impure github:ryoppippi/nix-claude-code -- --version

継続利用では、プロジェクトのflake.nixに入力として追加し、開発シェルへ組み込みます。

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    nix-claude-code.url = "github:ryoppippi/nix-claude-code";
  };

  outputs = { nixpkgs, nix-claude-code, ... }:
    let
      system = "x86_64-linux";
      pkgs = nixpkgs.legacyPackages.${system};
    in {
      devShells.${system}.default = pkgs.mkShell {
        packages = [
          nix-claude-code.packages.${system}.default
        ];
      };
    };
}

nix developでシェルに入り、claude --versionを確認します。全ユーザー向けにpkgs.claude-codeとして使いたい場合は、flakeのoverlayをnixpkgs.overlaysへ追加する方法もあります。導入元がコミュニティ製であること、Nixのロックファイルに依存することを理解したうえで、個人開発や検証環境から始めると判断しやすいでしょう。

出典: https://github.com/ryoppippi/nix-claude-code

Nixでの更新とバージョン固定の考え方

Nixで導入したClaude Codeは、Claude自身の自動更新に任せず、Nixの入力やパッケージ更新として扱います。nixpkgsのチャンネルを使う場合は、通常のNixOS更新と同じく、更新内容を確認してから反映します。

1. flakeを使っている場合は、まずロックファイルの差分を確認します。

   nix flake lock --update-input nixpkgs
   git diff -- flake.lock
   

2. 問題がなければNixOSまたはHome Managerを反映します。

   sudo nixos-rebuild switch --flake .#ホスト名
   home-manager switch --flake .#ユーザー名
   

3. 更新後にclaude --versionとclaude doctorを実行し、プロジェクトで小さな変更だけを試します。

最新リリースを追い続けたい場合でも、運用マシンではflake.lockをコミットしておくと、問題が起きたときに直前の入力へ戻せます。逆に、毎回github:ryoppippi/nix-claude-codeを直接実行する方法は検証向けです。どの版を使ったかを残したいなら、flakeで固定してから更新日を決めて取り込んでください。

NixOSで起きやすいエラーと対処

attribute 'claude-code' missing

利用中のnixpkgsが古い、または対象システム向けの定義がまだ入っていない可能性があります。nix search nixpkgs claude-codeで確認し、チャンネルを更新するか、flakeの入力をnixos-unstableへ切り替えます。無理に古い記事のclaude-code-binへ戻すのではなく、現在のパッケージ定義を基準にします。

has an unfree license

nixpkgs.config.allowUnfreePredicateがパッケージ評価へ届いていません。configuration.nixだけでなく、Home Managerを別のpkgsで初期化していないかも確認します。専用flakeのREADMEにある許可名はflake側のパッケージ名に合わせる必要があるため、lib.getNameの結果を確かめてから設定してください。

動的リンカーやFHSに関するエラー

NixOSは一般的なLinuxとファイル配置が異なるため、公式サイトのバイナリをcurlで直接~/.local/binへ置くと、/lib64/ld-linux-x86-64.so.2が見つからないエラーになることがあります。まずnixpkgs版を使い、それでも実行中に取得される追加バイナリで止まる場合は、nix-claude-codeが提供するLinux向けFHSラッパーを検討します。

claudeが見つからない

システム構成へ追加したのか、Home Managerのユーザー環境へ追加したのかを確認します。command -v claude、echo $PATH、home-manager generationsを順に確認し、反映後に新しいシェルを開いてください。開発シェルだけに入れた場合は、プロジェクトでnix developへ入らない限りコマンドは見えません。

導入後に確認したいログインと安全設定

インストールできても、利用するアカウントと権限の確認が必要です。公式ドキュメントでは、Claude Codeの利用にPro、Max、Team、Enterprise、またはConsoleのアカウントが必要と案内されています。無料プランだけではログイン後に利用できないため、先に契約状態を確認してください。

1. claudeを起動し、ブラウザ認証または利用するAPIプロバイダーの設定を完了します。

2. claude doctorでバージョン、設定ディレクトリ、接続状態を診断します。

3. 重要なリポジトリでは、最初に読み取りだけの依頼を出し、変更が必要な場合はgit diffで差分を確認します。

4. .env、秘密鍵、認証ファイルを読み取らせない設定をHome Managerへ記録し、認証情報をGitへコミットしないようにします。

5. 更新前にflake.lockのコピーまたはコミットを残し、問題が起きたときに以前の世代へ戻せる状態にします。

Linuxの認証情報は、公式ドキュメント上では標準設定ディレクトリ内の.credentials.jsonに保存されます。Nixの設定ファイルへトークンを直書きせず、認証ファイルの権限とバックアップ先を分けて管理するのが安全です。

出典: https://code.claude.com/docs/en/authentication

出典: https://code.claude.com/docs/en/installation