Run a real GNU/Linux distro on any Android device over ADB — no root, no app to install.
::: :::::: ::::::::
:+: :+::+: :+: :+:
+:+ +:++:+ +:+
+#+ +:++#+ +#++:++#++
+#+ +#++#+ +#+
#+# #+##+# #+# #+# ULS — Universal Linux Shell
######## ##################
ULS sets up a rootfs container environment on any ADB-connected Android device, then boots an interactive Linux shell into it — all orchestrated from your Mac. Starting with Android via ADB, with more targets on the roadmap.
- Requirements
- Install from a Release
- Quick Start
- Commands
- Supported Distros
- Device Requirements
- Uninstall
- Contributing a Distro
- License
| What | Details |
|---|---|
| Mac | Apple Silicon (arm64) |
| ADB | brew install android-platform-tools |
| Android device | ARM64 or ARMv7, Android 8+ |
| USB cable | Or an already-paired wireless ADB connection |
Run directly in your terminal:
curl -fsSL https://raw.githubusercontent.com/Jaseunda/uls/main/install.sh | bashThis will:
- Automatically download the latest release
.zipfrom GitHub Releases - Verify integrity against
SHA256SUMS - Extract and install
ulsinto~/.uls/bin - Symlink to
/usr/local/bin(or$HOME/.local/bin) so it's in your$PATH - Clear macOS Gatekeeper quarantine flags automatically
- Download the latest
uls-<version>.zipfrom the Releases page. - Unzip and install:
unzip uls-<version>.zip
cd uls-<version>
./install.sh- Verify:
uls --helpTip: If your shell doesn't pick up the PATH change, add
export PATH="$HOME/.uls/bin:$PATH"to your~/.zshrcor~/.bashrc.
Connect your Android device over USB and run:
uls setupThis will:
- Detect all connected ADB devices and let you pick one
- Let you choose a Linux distro (Arch Linux, Ubuntu, Debian, Alpine, …)
- Save a per-device config for future commands
uls deployDownloads the chosen distro bootstrap tarball matched to your device's CPU, then configures and extracts it on the device. First run takes a few minutes depending on your connection speed.
uls login arch # or: ubuntu, debian, alpine, etc.Drops you into a full interactive Linux shell on the device.
pacman, apt, apk — all work.
| Command | What it does |
|---|---|
uls setup |
Interactive device onboarding + distro selection |
uls deploy |
Download + push distro rootfs to device |
uls login <distro> |
Enter the Linux container (real PTY) |
uls upgrade |
Re-push ULS files — updates an already-installed Linux |
uls repair |
Re-extract rootfs on-device (fixes corrupt installs) |
uls distros |
List available distros and download links |
uls monitor |
Watch USB/ADB device events in dmesg style |
uls uninstall |
Remove ULS environment + rootfs from device ⚠ |
uls deploy --dry-run # show the plan without touching the device
uls deploy --no-download # use already-cached tarballs
uls deploy --repair # re-extract rootfs from cached tarball
uls login arch 'echo hello' # run a one-shot command inside the container| ID | Name | Arches |
|---|---|---|
archlinux |
Arch Linux (latest rolling) | arm64, armv7 |
ubuntu |
Ubuntu 24.04 LTS (Noble) | arm64, armv7 |
debian |
Debian 12 (Bookworm) | arm64, armv7 |
alpine |
Alpine Linux 3.24 | arm64, armv7 |
Run uls distros to see the live list with download links.
Want to add a distro? See Contributing a Distro.
- CPU: ARM64 (
arm64-v8a) or ARMv7 (armeabi-v7a) - Android: 8.0+ (API level 26+)
- System support: Kernel must allow container ptrace syscalls. Galaxy-class and standard ARM64 devices generally work.
uls uninstall # from the phone
uls uninstall --dry-run # preview what would be deletedcd <the release folder you downloaded>
./uninstall.sh # removes ~/.uls and the PATH symlinkThe distro catalog is community-maintained in this folder's latest.json.
To add a new distro or fix a dead mirror:
- Fork this repo.
- Edit
latest.json— add your entry under"distros". - Verify each URL is reachable:
curl -sIL --max-time 20 <url> - Open a PR — title format:
[catalog] Add <distro-name> (<arch>)
See CONTRIBUTING.md for the full guide and entry format.
This repository contains two distinct licenses:
| What | License |
|---|---|
Catalog data (latest.json, CONTRIBUTING.md, community docs) |
MIT — free to use, modify, and redistribute |
uls binary and install.sh (distributed via Releases) |
Proprietary — see the NOTICE file inside each release ZIP |
The uls binary is proprietary software © 2026 Jaseunda. Redistribution is not permitted without written permission. Third-party components (proot GPLv2, Arch Linux ARM) are credited in each release's NOTICE.