Bun-Termux

Run Bun on Termux (Android) without proot.

Installation   |   Documentation   |   Known Issues   |   Credits

Quick Start

1. Install

Option 1: Manager

curl -fsSL "https://raw.githubusercontent.com/Happ1ness-dev/bun-termux/main/helper_scripts/bun-termux-manager" | bash -s install

Option 2: Manual

# Prerequisites
pkg install git curl clang make glibc-repo python
pkg install glibc-runner

# Bun install script will skip bashrc if it doesn't exist
touch ~/.bashrc

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Make bun install visible
source ~/.bashrc

# Obtaining bun-termux source
git clone https://github.com/Happ1ness-dev/bun-termux.git
cd bun-termux

# Build and install wrapper
make && make install

2. Test

bun --version

# --bun/-b to force bun instead of node
bun --bun x cowsay "bun-termux works!"

# "--os=android" helps with some native modules
BUN_OPTIONS="--os=android" bun install -g cowsay

cowsay "bun-termux works!"

Tip

Symlink bun as node: If you don't have Node installed, some scripts may fail.

ln -s $HOME/.bun/bin/bun $HOME/.bun/bin/node

How It Works

Bun is built for glibc, not Android's bionic libc, and needs access to paths that Android restricts. bun-termux solves this with two components:

1. Wrapper (bun) Uses "userland exec" to launch the real Bun binary through glibc's dynamic linker. This technique means bun build --compile outputs embed the wrapper, making binaries work.

2. LD_PRELOAD Shim (bun-shim.so) Intercepts system calls to work around Android restrictions:

• Redirects /, /data, /storage → fake root directory (avoids permission denied)
• Redirects shebang paths (e.g. /usr/bin/env) → Termux prefix
• Fakes /proc/stat → makes os.cpus() work
• Stubs hardlinking → makes bun install work

See docs/README.md for the full technical breakdown.

Environment Variables

Variable	Description
BUN_INSTALL	Installation prefix (~/.bun)
BUN_BINARY_PATH	Override path to original bun binary
BUN_OPTIONS	Used by Bun for options/args

See docs/README.md for all variables and defaults.

Limitations

1. x86_64 support is experimental. Any feedback from x64 Android users is welcome.
2. Binaries built with bun build --compile have wrapper embedded, requiring buno, bun-shim.so and glibc to be present on the system where they run.
3. Bun install/add/update/remove commands might require BUN_OPTIONS="--os=android" env var if they install native modules.
4. If bun somehow fails to walk the current path due to permission error, it'll fail to get the current env vars too. I'll have to investigate why.
5. When using bun install, some module install scripts might fail without BUN_OPTIONS="--verbose".

Troubleshooting

For troubleshooting, refer to troubleshooting.md

Credits

This project is based on the userland exec technique from bun-termux-loader by @kaan-escober.

While bun-termux-loader focuses on creating self-contained bundled binaries with embedded Bun runtimes, this project takes a simpler approach: a lightweight wrapper that enables the standard Bun installation to work on Termux, including bun build --compile output, without embedding the entire Bun runtime.

License

MIT License - see LICENSE file for details.