Claude Media
Claude Code Alpine Linuxセットアップの手順と注意点
Claude Codeチュートリアル

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

Claude CodeをAlpine Linuxで動かすために必要なbash・curl・libgcc・ripgrepの依存関係と、USE_BUILTIN_RIPGREP設定まで一次ソースの手順でまとめます。

読了目安 約12分

Alpineでcurlインストーラーがnot foundで止まる理由

Claude Codeの標準インストールコマンドはcurl -fsSL https://claude.ai/install.sh | bashですが、Alpineの最小構成イメージで実行するとnot foundで止まります。 Alpineはbashもcurlも最初から入れていないためです。musl libcやuClibcをベースにした他のディストリビューションも同じ扱いです。

必要になるのは、インストールコマンドのためのbash・curlと、実行時のlibgcc・libstdc++・ripgrepです。動作要件はAlpine Linux 3.19以上、4GB以上のRAM、x64またはARM64のプロセッサーです。npm経由なら、musl向けにはlinux-x64-muslとlinux-arm64-muslのバイナリが使われます。

FreeBSDはAlpineと違い、そもそも対応OSに入っていません。その場合の動かし方はClaude CodeをFreeBSDで動かす方法にあります。

手順の順番は「依存、リポジトリ、インストール、設定」

順序を間違えると、not foundか検索失敗のどちらかに行き着きます。

手順

Alpineでのセットアップ順

  1. 1

    依存パッケージを入れる

    bash・curl・libgcc・libstdc++・ripgrepをapk addでまとめて入れます。

  2. 2

    ripgrepが見つからなければcommunityリポジトリを足す

    apkがripgrepは無いと答える環境でだけ必要です。

  3. 3

    インストーラーを実行する

    依存が揃ってからなら、他のOSと同じコマンドです。

  4. 4

    settings.jsonで検索の向き先を変える

    USE_BUILTIN_RIPGREPを0にして、入れたripgrepを使わせます。

依存パッケージの導入とインストール

apk add bash curl libgcc libstdc++ ripgrep
curl -fsSL https://claude.ai/install.sh | bash

ripgrepがcommunityリポジトリにしかないとき

ripgrepはAlpineのcommunityリポジトリにあります。ripgrepはAlpineのcommunityリポジトリにあります。追加する行のURLのv3.22は手元のAlpineのバージョンに合わせ、バージョンはcat /etc/alpine-releaseで分かります。

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

USE_BUILTIN_RIPGREPが切り替えるもの

Claude Codeはripgrepを検索に使います。環境変数USE_BUILTIN_RIPGREPは、0にすると同梱のrgではなくシステムに入っているrgを使わせる設定です。Alpineではsettings.jsonのenvキーに入れます。

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

公式ページでは、この設定の扱いが場所によって少し違います。システム要件の節は「ripgrepは通常Claude Codeに含まれる」と書き、検索が失敗したら検索のトラブルシューティングを見るよう案内します。Alpineの節はripgrepを実行時に必要なものとして挙げ、0の設定まで求めます。トラブルシューティングの側は、同梱のripgrepが動かない環境があるとして、システムのパッケージを入れてこの設定で向けるやり方を示します。つまりAlpineでは、ripgrepの導入と0の設定を組にして扱うのが公式の手順です。

この設定を忘れると、Search tool、@fileの候補、カスタムエージェントやスキルの検出が空振りします。ripgrepは入れたのに検索だけ失敗するので、原因の見当がつきにくい症状です。同じ症状はArch Linuxでも出ます。pacmanでの直し方はArch LinuxでClaude Codeの検索が効かない原因と直し方にあります。

同梱のrgが使えないことで困るのは、検索ツールだけではありません。カスタムコマンド、サブエージェント、出力スタイルの検出もripgrepに頼っています。こちらは別の環境変数CLAUDE_CODE_USE_NATIVE_FILE_SEARCHを1にするとNode.jsのファイルAPIで探す方式へ切り替わります。ただしGrepツールやファイル検索ツールには効きません。検索ツール側を直すのは、あくまでUSE_BUILTIN_RIPGREPです。

インストール方法による違い

同じAlpineでも、導入経路によって先に用意するものが変わります。

くらべる

導入経路ごとの前提

bash と curl が要る

curlインストーラー

インストールコマンドの実行にbashとcurlが必要です。実行時の依存は別に入れます。

Node.js 22 以上

npm

bashとcurlは要りません。Node.jsが22より古いとインストール時にEBADENGINEの警告が出ますが、失敗はしません。

鍵とリポジトリを登録

apkリポジトリ

署名鍵をダウンロードしてリポジトリを足し、apk add claude-codeで入れます。更新もapkで行います。

npmとNode.js入りイメージの場合

npmのパッケージはプラットフォームごとのoptional dependencyとしてネイティブバイナリを取得し、インストール後のclaudeはNode.jsを呼びません。node:22-alpineのようなイメージを使っていても、libgcc・libstdc++・ripgrepは別に必要です。Node.jsが入っているかどうかは、バイナリの実行時依存と無関係だからです。

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

apkリポジトリから入れる場合

stableチャンネルを登録する手順は、鍵の取得とリポジトリの追加とapk addの3行です。

wget -O /etc/apk/keys/claude-code.rsa.pub \
  https://downloads.claude.ai/keys/claude-code.rsa.pub
echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories
apk add claude-code

latestに切り替えるときは、stableの行をsedで消してからlatestの行を足します。

取得した鍵はsha256sum /etc/apk/keys/claude-code.rsa.pubで検証でき、公式の値は395759c1f7449ef4cdef305a42e820f3c766d6090d142634ebdb049f113168b6です。後からの更新はapk update && apk upgrade claude-codeです。

apt・dnfも含めたチャンネルの扱いはClaude Code apt installでのLinuxパッケージ導入と更新に、鍵そのものの検証はClaude CodeのGPG署名検証にまとめています。

サンドボックスを使うときの追加パッケージ

LinuxとWSL2のサンドボックスはbubblewrapとsocatに依存します。サンドボックスのページに手順が載っているのはUbuntu/Debian(apt-get)とFedora(dnf)で、Alpineのapkの例はありません。

足りない依存は、セッション内の/sandboxのDependenciesタブにripgrep・bubblewrap・socat・seccompフィルターのうち何が無いかとして表示されます。インストールして再起動した後にタブが出なければ、すべて揃っています。コンテナ内でOperation not permittedが出るときの対処や、AppArmorが絡むUbuntu固有の事情はClaude Code Ubuntuインストールで扱っています。

Error loading shared libraryが出たとき

インストール後にlibstdc++.so.6やlibgcc_s.so.1が見つからないというエラーが出たら、原因は2通りです。

切り分け

共有ライブラリのエラーの原因

  • glibc環境なのにmusl版が入った

    muslのクロスコンパイル用パッケージが入っているglibc環境で、インストーラーがmuslと誤判定した場合です。インストールを消して入れ直します。

  • 本当にAlpineで、依存が足りない

    apk add libgcc libstdc++ ripgrepで足ります。ripgrepが見つからないときは、前述のcommunityリポジトリを足します。

どちらなのかは、ldd --version 2>&1 | head -1で決まります。muslと出ればAlpineとして正しい判定で、GNU libcやGLIBCと出れば前者です。足りないライブラリそのものは、次のコマンドで一覧できます。

ldd "$(command -v claude)" | grep "not found"

何も出なければ、共有ライブラリは解決できています。判定コマンドと環境別の対処をさらに詳しく並べたものはlibstdc++.so.6エラーの原因と対処にあります。

導入後のバージョンとヘルスチェック

claude --version
claude doctor

claude --versionは、バージョン番号に(Claude Code)が付いた1行を返します。claude doctorは、公式のCLIリファレンスでは読み取り専用の診断とされています。セッションを起動せずに、インストールの状態と設定ファイルの検証エラーを見られます。

設定が効いたかは、claude doctorのSearch:の行で確かめます。システムのripgrepに切り替わっていれば、OK (bundled)ではなくそのパスが表示されます。あわせてwhich rgでシステム側のrgのパスを見て、検索ツールを実際に呼んで結果が返るかも試します。WSLのように、検索結果が少なくてもclaude doctorがSearchをOKと表示する環境があるので、この行だけで済ませず検索ツールの結果で確かめます。

Alpine対応の経緯とv2.1.239の修正

Alpineとmuslの対応はv1.0.73(2025年8月11日)で追加されました。当時から「ripgrepは別に入れる」という条件が付いており、今の手順はその延長にあります。

v2.1.239(2026年8月21日)では、musl向けのビルドで画像の貼り付け、クリップボード、音声キャプチャーのアドオンが読み込まれるようになりました。以前はglibc向けのバイナリが実行環境に拒否されていた、という説明です。Alpineでこれらの機能が動かなかったなら、バージョンを上げれば解消する可能性があります。

Dockerイメージに依存を焼き込む

毎回同じ依存を入れ直さずに済むよう、alpineをベースにするDockerfileでは依存の導入を早い層に置きます。アプリケーションのコピーより前に置けば、アプリ側の変更でこの層のキャッシュが捨てられません。USE_BUILTIN_RIPGREPは環境変数でもあるので、settings.jsonの代わりにENVで渡す形も取れます。

FROM alpine:3.22
RUN apk add --no-cache bash curl libgcc libstdc++ ripgrep
ENV USE_BUILTIN_RIPGREP=0
ENV PATH="$HOME/.local/bin:$PATH"
RUN curl -fsSL https://claude.ai/install.sh | bash

インストーラーはclaudeを~/.local/bin/claudeに置くので、後続のRUNやCMDからclaudeを呼ぶなら、PATHにこのディレクトリが要ります。

使い捨てのCIコンテナでも、依存の導入は省けません。イメージの層を削るときも、実行時の依存は残します。

まとめ

not foundなら依存の不足、検索だけの失敗なら0の設定漏れ、libstdc++.so.6ならldd --versionでmusl・glibcのどちらかを調べるのが入口になります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →