Py2Droid is CPython 3 compiled for Android and packaged as a Magisk module. It provides system-level Python access without requiring Termux or other userland environments.

Built following official Python for Android guidelines, stripped of unnecessary components for minimal size.

1. Download the latest release from Releases
2. Install via your root manager (Magisk/KernelSU/APatch)
3. Reboot your device
4. Start using Python:

   python3 --version
   pip3 install --user requests

Use Python instead of shell scripts in your modules. Python is available as a dependency or runtime for complex logic.

Get lightweight Python access at boot time without Termux overhead. Perfect for automation scripts and utilities.

Note: Py2Droid is not a Termux replacement. They serve different purposes.

• Android: 5.0+
• Architecture: ARM64 or x86_64
• Root: Magisk/KernelSU/APatch

Py2Droid runs in a bare Android environment (device with minimal shell, without Linux userland tools):

• No GUI support - No X11/Wayland, so no Tkinter
• Limited native extensions - Most packages with C/C++/Rust code don’t provide Android wheels, and you can’t compile them on-device
• Some stdlib modules unavailable - Modules requiring missing system libraries may not work
• Root required - System directory access needed

⚠️ Upgrading from v0.2? Read this before updating to v0.3+

# Check Python version
python3 --version

# Run a script
python3 script.py

# Install packages (always use --user!)
pip3 install --user requests beautifulsoup4

Pip is included since v0.3.0. If you need to reinstall it:

python3 -m ensurepip --user
# Reboot or source the environment
pip3 --version

# Create venv
python3 -m venv venv

# Activate (must load env.sh first!)
. /data/adb/py2droid/env.sh
. venv/bin/activate

# Install packages
pip3 install -r requirements.txt

# Run your app
python3 main.py

Wrappers are available:

# customize.sh example
cd "${MODPATH}" || exit 1
python3 main.py

Wrappers aren’t mounted yet. Load the environment manually:

# post-fs-data.sh example
. /data/adb/py2droid/env.sh  # Load Py2Droid environment

cd "${0%/*}" || exit 1
python3 main.py

Create /data/adb/py2droid/.shrc to customize the environment:

# Example .shrc
export NAME="Mrakorez"
hello() { echo "Hello, ${NAME}!"; }

This file is sourced when loading env.sh (not during module installation).

Py2Droid uses /data/adb/py2droid as its home directory:

/data/adb/py2droid/
├── .cache/           # Cache directory (XDG_CACHE_HOME)
├── .config/          # Config directory (XDG_CONFIG_HOME)
├── .local/
│   ├── bin/          # User binaries (XDG_BIN_HOME)
│   ├── share/        # Shared data (XDG_DATA_HOME)
│   └── state/        # State files (XDG_STATE_HOME)
├── .tmp/             # Temporary files (TMPDIR)
├── env.sh            # Environment loader
└── usr/              # Python installation (PREFIX)
    ├── bin/          # python3, pip3, etc.
    └── lib/          # Python libraries

Commands like python3 in /system/bin are wrapper scripts:

#!/system/bin/sh
. "/data/adb/py2droid/env.sh" && exec python3 "$@"

These wrappers:

• Load the Py2Droid environment
• Execute the actual command
• Are created automatically at boot for new commands
• Are removed if the underlying command is uninstalled

Use Python commands directly from any shell:

python3 -c "print('Hello')"
pip3 install --user requests

Pros:

• Works from anywhere
• Doesn’t affect your current environment
• Simple to use

Cons:

• New commands require reboot to become available

Source the environment for immediate access to all changes:

. /data/adb/py2droid/env.sh

# Now everything is available immediately
pip3 install --user pipx
pipx install cowsay
cowsay -t "No reboot needed!"

Pros:

• Immediate access to newly installed commands
• Full environment control

Cons:

• Overrides your current environment (including HOME, PATH, etc.)
• Only works in POSIX-compatible shells (sh, bash, zsh, ash)

Follow CPython Android build prerequisites

# Clone the repo
git clone https://github.com/Mrakorez/py2droid.git
cd py2droid

# Set up Python environment
python -m venv .venv
. .venv/bin/activate
pip install -r scripts/requirements.txt

# Build (see build.toml for configuration)
python scripts/build.py

# Output will be in dist/

Releases are automated via GitHub Actions:

1. Make changes and commit
2. Use release.py to prepare release
3. Push commits and tags
4. GitHub Actions builds and publishes automatically

MIT License - See LICENSE for details.