Claude Code Alpine Linuxセットアップの手順と注意点

Alpine Linuxでcurlインストーラーがそのまま失敗する理由

Claude Codeの標準インストールコマンドはcurl -fsSL https://claude.ai/install.sh | bashですが、Alpineの最小構成イメージにこのまま流すとnot foundエラーで止まります。Alpineは素の状態でbashとcurlを含んでいないためです。musl libcベースの他のディストリビューションでも同様の壁にあたります。

先に依存パッケージを揃えれば、インストールコマンド自体は他OSと変わりません。この記事はAlpine固有の依存関係と設定に絞って解説します。

実行前に用意する依存パッケージ

インストールコマンドの実行にはbashとcurl、実行時にはlibgcc・libstdc++・ripgrepが要ります。まとめて導入します。

apk add bash curl libgcc libstdc++ ripgrep

導入できたら、通常のネイティブインストーラーがそのまま使えます。

curl -fsSL https://claude.ai/install.sh | bash

ripgrepがcommunityリポジトリに無いと言われたとき

Alpineではripgrepがcommunityリポジトリに入っているため、mainリポジトリしか有効になっていない環境ではapk addが失敗します。自分のAlpineバージョンをcat /etc/alpine-releaseで確認し、該当するcommunityリポジトリの行を追加してください。

echo "https://dl-cdn.alpinelinux.org/alpine/v3.22/community" >> /etc/apk/repositories
apk update
apk add ripgrep

v3.22の部分は手元のAlpineバージョンに合わせて書き換えます。

USE_BUILTIN_RIPGREPを設定する

Claude Codeは既定で同梱のripgrepバイナリを使おうとしますが、Alpineのようなmusl libc環境ではこの同梱バイナリが動作しません。apk addで導入したripgrepを使わせるには、settings.jsonのenvキーにUSE_BUILTIN_RIPGREPを0で追加します。

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

この設定を入れないまま検索機能を使うと、ripgrepを導入したはずなのに検索だけ失敗するという分かりにくい症状になります。原因の切り分けに迷ったら、まずこの設定が入っているかを疑ってください。

設定が効いているかどうかはwhich rgでパスを確認し、apk info -L ripgrepで導入したパッケージが同じパスにファイルを配置しているかを見比べると切り分けやすくなります。

システム要件とハードウェアの前提

Alpine Linuxは3.19以上がClaude Codeの動作要件です。ハードウェア要件はディストリビューションを問わず共通で、4GB以上のRAMとx64またはARM64プロセッサが前提になっています。コンテナ環境で最小構成のAlpineイメージを使う場合、RAM割り当てを絞りすぎるとインストール自体は成功してもセッション実行時に不安定になることがあるため、割り当てメモリはこの下限を意識しておくと安全です。

npmでインストールする場合

npm経由でも同じ依存関係が前提になります。npmパッケージはプラットフォームごとのoptional dependencyとしてネイティブバイナリを取得する仕組みで、Alpineのようなmusl環境向けにはlinux-x64-musl・linux-arm64-muslが使われます。

v2.1.198以降はNode.js 22以上がnpmインストールの要件です。古いバージョンのNode.jsでもEBADENGINE警告が出るだけでインストール自体は完了しますが、node:22-alpineのようにNode.js 22系のイメージを使っておくと警告を避けられます。

npm install -g @anthropic-ai/claude-code

bashとcurlはインストールスクリプトを使わないnpm経由では不要ですが、libgcc・libstdc++・ripgrepはバイナリの実行時依存としてどちらの導入方法でも変わらず必要です。

既存のNode.jsベースAlpineイメージに追加する場合

node:22-alpineのようなNode.js入りのAlpineイメージを使っている場合でも、bash・curl・libgcc・libstdc++・ripgrepの導入は別途必要です。npmでインストールしたパッケージが取得するのはNode.js向けのスクリプトではなくプラットフォームごとのネイティブバイナリで、インストール後のclaudeコマンドはNode.jsランタイムを介さずに直接実行されます。そのため、コンテナに既にNode.jsが入っているという理由だけでmusl向けの依存関係を省略することはできません。

apkパッケージマネージャーで導入する場合

システム管理の都合でapkリポジトリからの導入を選ぶ場合は、署名鍵の取得とリポジトリ登録が別途必要です。手順とstable/latestチャンネルの切り替えはClaude Code apt installでのLinuxパッケージ導入と更新にまとめてあり、Alpine向けのapkタブの内容がそのまま該当します。

サンドボックス機能を使う場合の追加パッケージ

Claude Codeのサンドボックス化されたBashツールをAlpine上で有効にするには、bubblewrapとsocatを追加で導入します。

apk add bubblewrap socat

サンドボックスの権限モデルやAppArmorがらみの落とし穴は多くがUbuntu固有の話です。仕組み自体の解説はClaude Code Ubuntuインストールにまとめているので、bubblewrap導入後に動作しない場合はそちらを参照してください。

インストール後の確認

導入が終わったら、バージョン表示とヘルスチェックの2つで確認します。

claude --version
claude doctor

claude doctorはインストールの健全性・設定ファイルの検証エラー・修正案付きの警告を読み取り専用で表示します。サンドボックス関連の依存パッケージが揃っているかどうかはclaude doctorではなく/sandboxのDependenciesタブで確認します。検索が動かないという曖昧な症状に遭遇したら、原因を推測する前にまずclaude doctorの出力を読むのが最短経路です。

よくあるつまずき

bash: command not foundでインストーラーが動かない

Alpineの最小構成イメージそのままだと発生します。apk add bash curlを先に実行してから、インストールコマンドをやり直してください。

検索機能だけ動かない

ripgrepの導入自体は成功していても、USE_BUILTIN_RIPGREPを0にしていないと同梱バイナリを使おうとして失敗します。settings.jsonのenvキーを見直してください。

Error loading shared library libstdc++.so.6が出る

インストーラーがmusl向けとglibc向けのどちらか誤ったバイナリ変種を取得したサインです。まずldd --version 2>&1 | head -1を実行し、muslと表示されればAlpineとして正しい判定です。GNU libcやGLIBCと表示された場合は、glibc環境なのにmusl版バイナリが入ってしまっているため、インストールをやり直してください。Alpineとして正しく判定されている場合は、このエラーはlibgcc・libstdc++・ripgrepが未導入であることを意味するので、この記事の「実行前に用意する依存パッケージ」の手順をやり直します。判定コマンドと環境別の対処をさらに詳しく整理したものはlibstdc++.so.6エラーの原因と対処にまとめています。

Dockerのbaseイメージで毎回同じ依存を入れ直している

alpineをbase imageにしたDockerfileでは、RUN apk add bash curl libgcc libstdc++ ripgrepをレイヤーの早い段階に置き、USE_BUILTIN_RIPGREPの設定もイメージに焼き込んでおくとビルドのたびにやり直さずに済みます。依存パッケージのインストールをアプリケーションコードのコピーより前の層に置いておけば、アプリケーション側の変更だけではこの層のキャッシュが破棄されず、ビルド時間の短縮にもつながります。

よくある質問

AlpineベースのDockerコンテナでもこの手順は同じですか

同じです。Dockerfile内でapk add bash curl libgcc libstdc++ ripgrepを実行し、USE_BUILTIN_RIPGREPの設定を含めてから通常のインストールコマンドを実行します。CI専用の使い捨てコンテナであっても、依存パッケージの導入手順自体を省略することはできません。

サンドボックス機能はAlpineでも使えますか

使えます。apk add bubblewrap socatで依存パッケージを揃えれば動作します。AppArmorの制限のようなUbuntu特有の追加対応は不要です。

apt/dnfのようにstable/latestチャンネルを選べますか

選べます。apkもリポジトリベースでの導入に対応しており、チャンネルの切り替え方法は前段で紹介したapt/dnf/apk向けの記事にまとめています。リポジトリの署名鍵をさらに詳しく検証したい場合はClaude CodeのGPG署名検証も参照してください。手元のセキュリティ審査で署名の真正性まで確認したいときに役立ちます。

npmでインストールする場合も依存パッケージは必要ですか

必要です。bashとcurlはインストールスクリプトを使わない場合は不要ですが、libgcc・libstdc++・ripgrepはバイナリの実行時依存なのでnpm経由でも変わりません。導入経路が違っても、実行時に読み込まれるネイティブバイナリの中身自体は共通しています。

Alpineのバージョンによって手順は変わりますか

communityリポジトリのURLに含まれるバージョン番号だけが変わります。cat /etc/alpine-releaseで確認し、v3.22の部分を手元のバージョンに合わせてください。

対応しているAlpineのバージョンはいくつからですか

Alpine Linux 3.19以上が動作要件です。それより古いバージョンでは動作確認の対象外になるため、まずcat /etc/alpine-releaseで手元のバージョンを確認し、古い場合はアップグレードを検討してください。

まとめ

Alpine LinuxでClaude Codeを動かす鍵は、インストール前にbash・curlを、実行時にlibgcc・libstdc++・ripgrepを揃えることです。ripgrepがcommunityリポジトリにしか無い点と、導入後にUSE_BUILTIN_RIPGREPを0に設定する点を忘れると、検索機能だけが動かないという分かりにくい症状に行き着きます。パッケージマネージャー経由での導入やサンドボックス機能の詳細は、それぞれ本文で紹介したapt/dnf/apk向けの記事とUbuntu向けの記事を参照してください。導入経路とサンドボックス設定は別々に検討できるので、必要な部分だけつまみ読みしても問題ありません。