claude-code-android

Claude Code on Android

[!TIP] Upgrading, or hitting a launch error or a "Checking connectivity" hang? See Troubleshooting for the recovery steps. Your login and settings are kept.

Before You Start

What you need in place before any command in this guide can succeed:

These three prerequisites are for Path A and Path B, which both run in Termux. Path C, which runs on the Android Virtualization Framework (AVF, Android's built-in support for running a real Linux virtual machine), does not use Termux at all: it needs a Pixel 6 or later on Android 16 or later with Developer options turned on. If that is your setup, skip ahead to Path C: AVF Linux VM.

1. An aarch64 (64-bit ARM) Android phone, Android 8 or later. Most Android phones from 2018 onward qualify. A few budget Samsung A-series models ship a 32-bit OS on 64-bit hardware and will not work; see the Troubleshooting entry on armv7l / armv8l if uname -m (a command that prints your device's CPU architecture) returns those once you have a terminal open.
2. A Claude account (Pro, Max, Team, Enterprise, or a Console / API account, meaning a pay-as-you-go developer account at console.anthropic.com). Claude Code uses your existing Anthropic login.
3. Termux installed from F-Droid or GitHub. Termux is the terminal-emulator app the install commands below run in. The upstream Termux maintainers recommend F-Droid or their GitHub releases for most users. There is a Google Play build but as of the upstream README it is an experimental branch with missing functionality and bugs, and the upstream project recommends against it for most users. See github.com/termux/termux-app for the full install source breakdown and current caveats from the Termux maintainers themselves.

If you have never used F-Droid or Termux before, the upstream maintainers already cover the install steps better than this repo can:

• F-Droid (the open-source Android app store you install as an APK): f-droid.org. The front page has the install instructions and the Play Protect prompt you may see on first launch.
• Termux on F-Droid: f-droid.org/en/packages/com.termux/. You can install F-Droid first and then install Termux from inside it, or download the Termux APK directly from that page.
• Termux project (background, FAQ, troubleshooting): github.com/termux/termux-app, wiki.termux.com.

Once Termux is open you will see a prompt that looks like ~ $. That is where the commands in Quick Install go. (Long-press to paste, or tap the on-screen Ctrl key then press V.)

Full prerequisites including the Termux:API source-matching rule: docs/install.md#prerequisites.

Quick Install

The repo documents three install paths. Pick one before pasting commands:

• Path A (native Termux). The official linux-arm64 claude binary, patched to run on Android, with a wrapper that checks once a day for a new version and updates transparently. About 5 to 10 minutes to install, a few hundred megabytes on disk, and about 200 MB more if you accept the recommended packages. One thing to know up front: on launch it points Claude Code's own DNS lookups at Google's public resolvers (8.8.8.8 / 8.8.4.4) to sidestep a connectivity hang, which overrides a VPN, split-tunnel, or Pi-hole resolver for those queries (see Security Model).
• Path B (proot-distro Ubuntu). Latest Claude Code installed via Anthropic's official installer inside a full Ubuntu environment. Heavier at ~2 GB on disk, but process.platform reports linux and standard Linux conventions all apply. (process.platform is the runtime identifier of the host operating system, which some tools branch on.)
• Path C (AVF Linux VM, experimental). Real Linux kernel via Android's built-in virtual machine support (the hypervisor). Doesn't use Termux at all. Needs a Pixel 6 or later on Android 16 or later. The Exynos Galaxy S26 / S26+ are reported to work but I have not lab-verified them; Snapdragon devices, including the S26 Ultra, are not supported.

Which should you pick? Path A is the default: it is what install.sh sets up, and it keeps itself current, so if you are not sure, start there. My own take on the tradeoffs is in the note below. Side-by-side comparison: docs/install.md#choose-your-path.

[!NOTE] Which path I run, and why: I run Path A (native Termux) myself. It is what install.sh sets up, it keeps itself current, and it is what I migrated my own daily driver to. If you would rather keep a patched-binary wrapper out of the loop, Path B (proot-distro Ubuntu) is the simplest way to keep Claude Code self-updating through Anthropic's official installer, the same as on a PC. Path C (AVF) is arguably the most genuinely native option, though its coverage is still narrow. Pick the one that fits your device; I am just sharing what I run.

If you are coming up from an older pinned 2.1.112 install, follow Upgrading from a pinned install. Not sure which install you have? claude --version reports Claude Code's own version (the 2.1.x number), not this repo's, so it will not tell you; see Which setup am I on? for a one-command check.

Path A: Native Termux

curl -fsSL https://raw.githubusercontent.com/ferrumclaudepilgrim/claude-code-android/main/install.sh -o install.sh
bash install.sh

The installer asks two yes/no questions, then runs unattended. When it finishes, type:

claude

Here is what install.sh does, start to finish:

• Installs Termux's glibc-runner and patchelf-glibc.
• Downloads the official linux-arm64 claude binary from Anthropic's CDN (the content-delivery servers the file is hosted on) and verifies the checksum (a fingerprint that confirms the download arrived intact from Anthropic) against Anthropic's published list. The binary and its checksum come from the same Anthropic host, so this catches a corrupted or truncated download; it is not upstream code signing and does not by itself prove the source was not compromised.
• Patches the binary's ELF interpreter so Android can run it. ELF (Executable and Linkable Format) is the standard format for Linux programs, and the "interpreter" is the loader it asks for at startup; this step points the binary at the Termux-provided one.
• Drops a wrapper at $PREFIX/bin/claude ($PREFIX is Termux's own install folder) that auto-checks for new claude releases once a day on launch.

The wrapper accepts a --update-now flag to force an immediate check; this is a Path A wrapper feature, not a built-in Claude Code flag. Want to read it first? View install.sh on GitHub before running.

Full walkthrough: docs/install.md.

Prefer the smallest, simplest install and do not need current claude? install-pinned.sh pins Claude Code 2.1.112 (the last version with a JS entry point) with no binary patching and no auto-updating wrapper. It stays at that version; install.sh above is the default for current claude.

[!IMPORTANT] Path A runs on a compatibility workaround. Anthropic ships Claude Code as a glibc-linked Linux binary, with no Android build. Termux runs on Android's Bionic C library, so any version past the old pinned 2.1.112 runs here only because install.sh patches the official linux-arm64 binary to load through Termux's glibc-runner. It works and stays current, but it is a shim, not native support.

The real fix is upstream. There is no official Android build today; adding one would need either a bun android-arm64 target or a static musl build. (bun is the JavaScript runtime Claude Code is bundled with; a static musl build would be a fully self-contained binary that does not rely on the host system's C library.) Until that ships, Path A depends on this patching step. Tracked at anthropics/claude-code#50270.

Path B: proot-distro Ubuntu

Latest Claude Code inside a full Ubuntu environment.

pkg install proot-distro -y
proot-distro install ubuntu && proot-distro login ubuntu

This may take a few minutes depending on connection speed.

Upon completion the prompt changes to something like:

root@localhost:~#

That means you are now inside Ubuntu rather than Termux. Inside Ubuntu:

apt update && apt upgrade -y
curl -fsSL https://claude.ai/install.sh | bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
claude

Full walkthrough: docs/install.md#path-b-proot-distro-ubuntu.

Path C: AVF Linux VM (Pixel 6+ with Android 16+, experimental)

Real Linux kernel via the Android Virtualization Framework. No Termux involved. Supported on Pixel 6 and later. The Exynos Galaxy S26 / S26+ are reported to work but I have not lab-verified them; Snapdragon devices, including the S26 Ultra, are not supported.