Bun on Termux

What is the type of issue?

Documentation is missing

What is the issue?

Missing Docs for Termux users

Intro

While the primary focus of Bun is not currently on Android platforms like Termux, this aims to help Termux users install and use Bun smoothly.

installation

To begin, refer to the official Bun installation documentation using the following command:

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

However, after installation, attempting to use Bun may result in a Command not found error.

Solutions

Native Termux

Start by addressing this issue with the only current viable solution — utilizing Termux's glibc package, which is detailed here.
After installation, set an alias using grun to process the binary correctly.

Open your preferred configuration file (e.g., vim ~/.zshrc).
Add the alias:

alias bun="grun ~/.bun/bin/bun"

Downsides

While this solution has its usecases, there are some downsides to consider:

Packages Are Limited:

Due to limitations with grun, Bun may encounter difficulties reading and processing node modules, resulting in errors like:

❯ bun run index.ts
error: Cannot find package "some-package" from "/storage/emulated/0/Download/some_project/index.ts"

Limited Functionality:

As of now, due to native permissions and issues with grun, the Bun binary isn't fully processed. Consequently, certain operations may not work correctly:

Installing packages:

❯ bun add axios
bun add v1.0.25 (a8ff7be6)  🔍 axios [6/6]error: FailedToOpenSocket downloading package manifest axioserror: axios@ failed to resolve

Using features like bunx or Bun's REPL:

❯ bun repl
error loading current directoryerror: CouldntReadCurrentDirectory----- bun meta -----Bun v1.0.25 (a8ff7be6) Linux arm64 #1 SMP PREEMPT Wed Dec 27 11:31:51 UTC 2023BunxCommand:Elapsed: 11ms | User: 4ms | Sys: 12msRSS: 33.55MB | Peak: 9.72MB | Commit: 33.55MB | Faults: 12----- bun meta -----0   0x720c4e24f81   ???2   ???3   ???4   ???5   ???6   ???Search GitHub issues https://bun.sh/issues or ask for #help in https://bun.sh/discord

Proot distro

For installation and usage of Bun on Termux with a better approach, follow these steps:

Install PRoot-Distro:
Execute the following command to install PRoot-Distro using Termux's packages:

apt update && apt install proot-distro -y

starting a session

proot-distro install ubuntu proot-distro login ubuntu # once installed you can use this anytime to start your Ubuntu terminal

make sure bun is installed in the new session
After installation, set an alias to run the Bun binary. Unlike native Termux, there are no external packages needed in this environment.

Open your preferred configuration file (e.g., vim ~/.zshrc).
Add the alias:

alias bun="~/.bun/bin/bun" # Or use the path where you have placed Bun's binaries

Restart Your Shell:
If you're using zsh, restart your shell to apply the changes:

exec zsh

Verify Installation:
Confirm the successful installation of Bun by running:

bun --version

downsides

Installing Packages:
Due to Bun not being optimized for Android architectures, it lacks the necessary permissions to access node_modules. However, a fix is available. Update your configuration file with the following:

alias bun=bun_function
# Function to handle installations with the "--backend=copyfile" flag to prevent an "access denied" error during package installations.
bun_function() {
  if [ "$1" = "add" ]; then
    shift
    ~/.bun/bin/bun add --backend=copyfile "${@}"
  else
    ~/.bun/bin/bun "$@"
  fi
}

Additional Notes

This doesn't intend to force developers to prioritize Termux support but serves as a guide for those with limited access to environments like Termux. Ideas and fixes presented here are mostly original, with clarifications drawn from insightful comments on related issues.

credits:

Special thanks to issue #5085 for providing insights into fixing package installations. Additionally, credit goes to Denos fix for addressing similar usage issues.

Where Did You Find It?

This issue post aims to address missing documentation for Bun on Termux. It is *not intended to compel developers to prioritize Termux support but rather serves as guidance for users with limited access to environments like Termux. The outlined solutions and insights are derived from mostly original ideas with additional clarification from comments on related issues, particularly issue #5085 and Denos fix.

Thanks for opening this issue with detailed ideas/workarounds. We have too many other things to prioritize over Android/Termux. If we add it to our docs, there is an implicit expectation that it is a supported platform, when in reality it is not.

understandable,
Considering the recent launch of Bun and other urgent matters, addressing concerns related to native Termux may not be the current primary focus. also, prioritizing support for Windows as of now is crucial to avoid potential complications from simultaneous extensive updates, which could negatively impact the ecosystem and workflow.

I made a shell script termux-pacman-glibc-setup.sh to setup glibc-runner with pacman on Termux and install Deno.JS and Bun.JS as a demo.

.bashrc:

alias bum=bun_function
# Function to handle installations with the "--backend=copyfile" flag to prevent an "access denied" error during package installations...that did not work for me:
bun_function() {
  if [ "$1" = "add" ]; then
    shift
    ~/.bun/bin/bun add --backend=copyfile "${@}"
  else
    ~/.bun/bin/bun "$@"
  fi
}

export PATH=$HOME/.bun/bin:$PATH

From a semi broken state with alias ubu='proot-distro login ubuntu' I ran:

dpkg --configure -a
pkg upgrade -y
ubu
rm -rf ~/.bun ~/.bun-install node_modules bun.lockb .bun-cache
hash -r
curl -fsSL https://bun.sh/install | bash

@cirospaciari

🎉 Solution for Running Bun Bundled Executables on Termux

I've solved the problem of running bun build --compile binaries on Termux and documented the root cause.

The Problem with `grun`

When running Bun via grun (or explicit ld.so), bundled executables fail because:

grun calls execve("/path/to/ld.so", ["ld.so", "./bun-app"], env)
The kernel sets /proc/self/exe → ld-linux-aarch64.so.1
Bun reads /proc/self/exe, opens ld.so, doesn't find the ---- Bun! ---- trailer
Falls back to CLI mode instead of running embedded JavaScript

$ grun ./my-app -e "console.log(require('fs').readlinkSync('/proc/self/exe'))"
/data/data/com.termux/files/usr/glibc/lib/ld-linux-aarch64.so.1  # ← Wrong!

✅ Working Solution: Userland Exec Wrapper

I created a Rust wrapper using the userland-execve crate that:

Loads ld.so via mmap() instead of execve()
Jumps to ld.so's entry point directly
/proc/self/exe stays pointing to the wrapper binary
Append the original binary's embedded JS data to the wrapper

This works because the kernel only updates /proc/self/exe on execve() syscalls.

Key trick for child processes: Use ld.so --library-path /glibc/lib instead of LD_LIBRARY_PATH so child processes (bash, ls, etc.) still use Bionic.

Full technical writeup: https://github.com/AlyBadaworked/droid-to-glibc/blob/main/SOLUTION.md

🔧 Proposed Simple Fix for Bun

Instead of this complex workaround, Bun could add a simple env var override:

// Before reading /proc/self/exe:
if (bun.getenvZ("BUN_SELF_EXE")) |path| {
    return path;
}

Then Termux users could simply:

export BUN_SELF_EXE="$(realpath ./my-app)"
grun ./my-app

I've opened an issue for this: #26752

Impact

This affects:

All bun build --compile binaries on Termux
The "Packages Are Limited" and "Limited Functionality" issues mentioned in this thread are likely related

cc @cirospaciari

@kaan-escober

@kaan-escober How did you install bun on Termux first?

@kaan-escober

@kaan-escober How did you install bun on Termux first?

https://github.com/tribixbite/bun-on-termux

@tribixbite

@tribixbite I already tried that, but it doesn’t seem to work.

Every Bun command fails with the same error:

~ $ bun run test.ts
error loading current directory
error: An internal error occurred (CouldntReadCurrentDirectory)

~ $ bun repl
error loading current directory
error: An internal error occurred (CouldntReadCurrentDirectory)

~ $ bun feedback test.ts
error loading current directory
error: An internal error occurred (CouldntReadCurrentDirectory)

~ $ bun create vite
error loading current directory
error: An internal error occurred (CouldntReadCurrentDirectory)

@tribixbite

@tribixbite I already tried that, but it doesn’t seem to work.

Every Bun command fails with the same error:

~ $ bun run test.ts
error loading current directory
error: An internal error occurred (CouldntReadCurrentDirectory)

~ $ bun repl
error loading current directory
error: An internal error occurred (CouldntReadCurrentDirectory)

~ $ bun feedback test.ts
error loading current directory
error: An internal error occurred (CouldntReadCurrentDirectory)

~ $ bun create vite
error loading current directory
error: An internal error occurred (CouldntReadCurrentDirectory)

https://github.com/tribixbite/bun-on-termux/blob/main/docs%2FTROUBLESHOOTING.md#couldntreadcurrentdirectory-error

Note: "the wrapper" is referring to the custom wrapper in that repo

@tribixbite

cool work @tribixbite. i just saw your repo.

Hi, I made a native wrapper that allows Bun to run in Termux without proot.

It's based on kaan-escober's bun-termux-loader, but takes a slightly different approach, making both bun and bun built binaries "just work" without many problems.

Constructive criticism and feedback are welcome :P
https://github.com/Happ1ness-dev/bun-termux

Bump

$ curl -fsSL https://bun.com/install | bash
#=#=#                                                                  ##O#-#                                                                                                                                                                                                               #                                                                      ####                                                                   #########                                                              #############                                                          ##################                                                     ########################                                               ###############################                                        #####################################                                  #############################################                          ####################################################                   ##########################################################             ################################################################       ######################################################################## 100.0%
bun was installed successfully to ~/.bun/bin/bun
Run 'bun --help' to get started
~ $ bun --help
bash: /data/data/com.termux/files/home/.bun/bin/bun: cannot execute: required file not found
$ uname -a
localhost 6.6.30-android15-8-g6b55ce738535-4k #1 SMP PREEMPT Thu Jan  1 00:00:00 UTC 1970 aarch64 Android

@ElYaiko

@ElYaiko can you try to manually install one of the android builds directly from gh releases, as I'm pretty sure the install script is the issue here now? For example the bun-linux-aarch64-android.zip should be what most need.

https://github.com/oven-sh/bun/releases/tag/bun-v1.3.14

I made a simple installation script.

https://gist.github.com/ErenayDev/9fd5010d6830297cfc5efc173ce89c00

bun
fish: Job 1, 'bun' terminated by signal SIGSYS (Bad system call)

i tested the bun build but it throws a bad syscall error

@ErenayDev

@ErenayDev it works 😍

#30859

Yay, I'll mark this overarching issue as completed by #29676 (or more precisely #29675) 🎉

https://bun.com/blog/bun-v1.3.14#freebsd-and-android-support

I fixed it it's now working with glibc wrapper The output shows no EACCES errors
Install from https://termuxvoid.github.io/

Or you can download the deb and read it's postinst to build working bun Natively for future version https://github.com/termuxvoid/repo/blob/main/dists/termuxvoid/main/binary-all/bun.deb

Navigation Menu

Repository navigation

Bun on Termux #8685

What is the type of issue?

What is the issue?

Missing Docs for Termux users

Intro

installation

Solutions

Native Termux

Downsides

Packages Are Limited:

Limited Functionality:

Proot distro

downsides

Additional Notes

credits:

Where Did You Find It?

🎉 Solution for Running Bun Bundled Executables on Termux

The Problem with `grun`

✅ Working Solution: Userland Exec Wrapper

🔧 Proposed Simple Fix for Bun

Impact

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Bun on Termux #8685

Description

What is the type of issue?

What is the issue?

Missing Docs for Termux users

Intro

installation

Solutions

Native Termux

Downsides

Packages Are Limited:

Limited Functionality:

Proot distro

downsides

Additional Notes

credits:

Where Did You Find It?

Activity

Electroid commented on Feb 4, 2024

n0thhhing commented on Feb 4, 2024

CodeIter commented on May 16, 2024

tribixbite commented on May 30, 2025

kaan-escober commented on Feb 5, 2026

🎉 Solution for Running Bun Bundled Executables on Termux

The Problem with grun

✅ Working Solution: Userland Exec Wrapper

🔧 Proposed Simple Fix for Bun

Impact

Jobians commented on Feb 18, 2026

tribixbite commented on Feb 25, 2026

Jobians commented on Feb 25, 2026

tribixbite commented on Feb 25, 2026

kaan-escober commented on Feb 26, 2026

Happ1ness-dev commented on Mar 5, 2026

ElYaiko commented on May 9, 2026

RiskyMH commented on May 14, 2026

ErenayDev commented on May 14, 2026

kaan-escober commented on May 15, 2026

Jobians commented on May 15, 2026

Jobians commented on May 15, 2026

RiskyMH commented on May 15, 2026

RiskyMH commented on May 15, 2026

Anon4You commented on Jun 5, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

The Problem with `grun`