*

What is Py2Droid?

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.

Quick Start

• Download the latest release from Releases
• Install via your root manager (Magisk/KernelSU/APatch)
• Reboot your device
• Start using Python:

python3 --version
   pip3 install --user requests

Why Py2Droid?

For Magisk Module Developers

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

For System Scripts

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

vs Termux

| Feature | Py2Droid | Termux Python | | ---------------- | ------------------------------- | ---------------------------- | | Version | Latest stable Python 3 | May lag behind | | Installation | Single module | App + packages | | Size (aarch64) | ~44 MB installed | ~60 MB installed | | Boot-time access | ✅ Available during early boot | ❌ Unavailable until unlock | | Location | /data/adb (always accessible) | /data/user (encrypted) | | Use case | System scripts, Magisk modules | Full development environment |

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

System Requirements

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

Limitations

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,

• Some stdlib modules unavailable - Modules requiring missing system libraries may not work
• Root required - System directory access needed

Breaking Changes

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

Usage

Basic Commands

# Check Python version
python3 --version
Run a script
python3 script.py
Install packages (always use --user!)
pip3 install --user requests beautifulsoup4

Installing pip

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

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

Virtual Environments

# 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

In Magisk Modules

customize.sh, service.sh, action.sh

Wrappers are available:

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

post-fs-data.sh, uninstall.sh

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

Customization

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).

How It Works

Directory Structure

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

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

Command Wrappers

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

Two Ways to Use Python

1. Wrappers (Quick & Isolated)

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

• New commands require reboot to become available

2. Direct Environment (Full Access)

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

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

Building from Source

Prerequisites

Follow CPython Android build prerequisites

Build Steps

# 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/

CI/CD

Releases are automated via GitHub Actions:

• Make changes and commit
• Use release.py to prepare release
• Push commits and tags
• GitHub Actions builds and publishes automatically

License

MIT License - See LICENSE for details.