AndroSH

AndroSH - Run Linux Distributions on Android (No Root, ADB/Shizuku Powered)

Run and manage full Linux distributions on your Android device - no root required.

Table of Contents

• Quick Start
• Features
• Supported Distributions
• Overview
• Screenshots
• Architecture
• Installation
• Updating
• Usage
• Use Cases
• Security & Privacy
• Components & Sources
• Troubleshooting
• Contributing
• License
• Author
• Support

Quick Start

# In Termux
apt update && apt install -y python git
git clone --depth 1 https://github.com/ahmed-alnassif/AndroSH.git
cd AndroSH
pip install -r requirements.txt
python main.py install

androsh setup demo --distro debian --type stable
androsh launch demo

Features

• Multi-distro: run several Linux distributions side by side (Arch, Fedora, Alpine, Debian, Ubuntu, Kali, Void, Manjaro, Chimera, openSUSE)
• ADB/Shizuku-powered Linux: run full Linux distributions through Android’s elevated Shell layer, with direct Android system integration - no root required
• SQLite-backed: fast, reliable tracking of your environments
• Isolated: each Linux environment runs through PRoot with userspace filesystem/process isolation
• GUI support: works with Termux:X11 for a full desktop environment - setup guide

Supported Distributions

Every distribution above ships from a verified rootfs source and runs in an isolated proot environment - no root required.

Overview

AndroSH lets you deploy and manage multiple full Linux distributions on Android by running PRoot through the ADB/Shizuku execution layer. This provides elevated Android-side execution without root while retaining direct Android system integration from inside the Linux environments.

Screenshots

Architecture

Android Device → ADB/Shizuku Execution Context→ Proot Virtualization → Linux Environment(s)

From inside any distro, you can reach into the Android system directly:

# List installed Android packages
pm list packages -f

# Kernel info
cat /proc/version

# Android system properties
getprop | grep version

# Network routes
ip route show

Installation

Requirements

• Android device with Shizuku installed and running
• Python 3.8+
• Termux or a compatible terminal emulator
• At least 2 GB free storage

Setup

# Install prerequisites in Termux
apt update && apt install -y python git

# Get AndroSH
git clone --depth 1 https://github.com/ahmed-alnassif/AndroSH.git
cd AndroSH

# Install dependencies
pip install -r requirements.txt

# Make the `androsh` command available globally
python main.py install

Updating

cd AndroSH
git pull
pip install -r requirements.txt

Usage

Deploy an environment

androsh setup production --distro debian --type stable

Launch it

androsh launch production
# You're now root inside the Debian environment
root@localhost:~# apt update && apt install python3 git

Manage environments

androsh list                       # See what's available to install
androsh lsd                        # See what's already installed
androsh clean production           # Free up space / remove temp files
androsh remove production --force  # Delete an environment

Manage distributions directly

androsh distro list                                              # List available distros
androsh distro info ubuntu                                       # Get details on a distro
androsh distro download alpine --type alpine-minirootfs --file alpine-edge.tar.gz

Full command reference

See AndroSH_Help.md for every command and flag, including verbosity control (--verbose / --quiet) and timestamp formatting (--time-style).

Use Cases

Learning Linux

androsh setup classroom --distro ubuntu --type stable
apt install gcc python3-dev git curl wget

Security research / penetration testing

androsh setup pentest --distro kali-nethunter --type full
apt install nmap metasploit-framework wireshark

Lightweight dev environments

androsh setup devops --distro alpine --type alpine-minirootfs
apk add build-base git nodejs npm docker-cli

On-the-go workstation

androsh setup field --distro debian --type stable
apt install vim tmux htop net-tools

Running several environments at once

androsh setup frontend --distro ubuntu -t stable
androsh setup backend --distro debian -t stable
androsh setup security --distro kali-nethunter -t nano
androsh lsd

Security & Privacy

• Android privilege boundary: Android-side operations run within the permissions available to the ADB/Shizuku execution context; no Android root is required.
• Process isolation: each environment runs sandboxed via proot
• Integrity checks: SHA-256 checksums validate every download
• No telemetry: zero data collection, everything stays local on your device
• Open source: every component is auditable

Components & Sources

Build pipelines: PRoot builder · BusyBox NDK sources · AndroSH core

All dependencies are traceable to their upstream sources and kept in sync with security updates.

Troubleshooting

Reset a broken environment

androsh setup <distro> --distro debian -t stable --resetup

Clean up temp files

androsh clean <distro>

Reinstall the global androsh command

cd AndroSH
python main.py install

Shizuku issues

• Confirm Shizuku is running and AndroSH is authorized in it
• If problems persist, reboot the device to restore the Shizuku service

Contributing

Contributions of all kinds are welcome - code, documentation, bug reports, feature ideas, translations, testing, or just sharing feedback. Whether you’re fixing a typo or adding support for a new distro, every contribution helps.

Ways to get involved:

• Code: fix bugs, add features, improve performance
• Documentation: improve the README, write guides, add examples
• Testing: try AndroSH on different devices/Android versions and report what you find
• Bug reports: open an issue with clear steps to reproduce
• Feature requests: suggest ideas or workflows you’d like to see supported
• Community support: help answer questions in issues/discussions

No contribution is too small - if you’re not sure where to start, open an issue and ask.

Set up a dev environment:

git clone https://github.com/ahmed-alnassif/AndroSH.git
cd AndroSH
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Contributors

License

GPLv3 - free for commercial and research use.

Author

Ahmed Al-Nassif

• GitHub: @ahmed-alnassif

Support

• Star the repo if you find it useful - it helps others discover the project
• Share it with friends, communities, or on social media if AndroSH has been useful to you
• Open an issue to report bugs
• Start a discussion to suggest features or ask questions
• Share your use case - tell us how you’re using AndroSH, it helps shape future development
• Spread the word by writing about it, making a video, or recommending it wherever Android/Linux enthusiasts hang out

Every bit of support, big or small, helps keep the project growing.