Metadata-Version: 2.4
Name: psutil-android
Version: 7.2.5
Summary: psutil, repackaged with a prebuilt aarch64 C extension extracted from Termux, so it installs and runs inside Termux on Android without a source build
Author-email: Giampaolo Rodola <g.rodola@gmail.com>
Maintainer-email: Hadi Cahyadi <cumulus13@gmail.com>
License: BSD 3-Clause License
        
        Copyright (c) 2009, Jay Loden, Dave Daeschler, Giampaolo Rodola
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without modification,
        are permitted provided that the following conditions are met:
        
         * Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
         * Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
         * Neither the name of the psutil authors nor the names of its contributors
           may be used to endorse or promote products derived from this software without
           specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
        ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
        ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
        (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
        LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
        ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
        SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
        ---
        
        Repackaging (Android build glue, this distribution) Copyright (c) 2026 Hadi Cahyadi.
        Same BSD 3-Clause terms apply.
        
Project-URL: Homepage, https://github.com/cumulus13/psutil-android
Project-URL: Upstream, https://github.com/giampaolo/psutil
Keywords: psutil,android,system,monitoring,process
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: Android
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# psutil-android

`psutil`, repackaged so it installs and imports as `psutil` **inside
Termux on Android** — no compiler, no NDK, no source build needed
on-device.

> **⚠️ Termux only.** This does not run on stock Android, Pydroid,
> QPython, Chaquopy, or any other embedded-Python runtime. See
> [Why this is Termux-specific](#why-this-is-termux-specific-not-any-android-device)
> below for exactly why, verified via `readelf`.

## Structure

```
psutil/
  _native/
    aarch64/_psutil_linux.abi3.so, meta.json
    arm/_psutil_linux.abi3.so, meta.json
    i686/_psutil_linux.abi3.so, meta.json
    x86_64/_psutil_linux.abi3.so, meta.json
  _native_loader.py   <- picks the right .so for platform.machine() at import time
  _android_compat.py  <- if loading fails, gives an exact reason instead of
                          a bare "cannot open shared object file"
  __init__.py, _common.py, _pslinux.py, ...   <- upstream psutil, unmodified
```

Each `.so` is extracted from Termux's own `python-psutil` package build
(`ghcr.io/termux/package-builder` + `termux/termux-packages`' actual
recipe), so it's linked correctly against that arch's Termux `libc`/
`libpython` — not a generic NDK cross-compile guess. `meta.json` next to
each `.so` is generated from the binary's real `NEEDED` entries
(`.github/scripts/gen_meta.py`, via `readelf`), not hand-typed, so it
can't drift from what the binary actually requires.

As of the current release, all four arches (`aarch64`, `arm`, `i686`,
`x86_64`) are built by CI and bundled in every published wheel — one
wheel works across every Termux-supported CPU. `_native_loader.py`
auto-selects the right one at import time.

## Why this is Termux-specific, not "any Android device"

Every bundled `.so` is hard-linked (RUNPATH) against Termux's own
runtime, confirmed via `readelf -d` on all four arches:

```
RUNPATH: /data/data/com.termux/files/usr/lib
NEEDED:  libandroid-support.so, libpython3.14.so, libc.so
```

So even with every arch bundled, this only runs where **all** of the
following hold:

- **Termux** is installed (not stock Android, not Pydroid/QPython/
  Chaquopy — none of those have `libandroid-support.so` or Termux's
  `libc.so` shim)
- CPU arch matches one of the bundled binaries (aarch64/arm/i686/x86_64
  covers every arch Termux itself ships for)
- Termux's Python minor version matches what that arch's binary was
  linked against (currently 3.14.x for all four, recorded per-arch in
  `meta.json`; each Termux Python update can require a rebuild — just
  re-run the release workflow)

When any of that doesn't hold, import fails with a specific diagnosis
(`_android_compat.py`), not a cryptic OS error — and suggests the
fallback: `pkg install clang make && pip install psutil`, which compiles
real upstream psutil from source on-device and isn't tied to any of the
above at all. That's the actually version-proof path; the bundled
binaries exist to skip needing a compiler on-device.

Tested on:
```
Linux localhost 5.10.136-android12-9-00005-gf9a66cbe7091-ab9177899 #1 SMP PREEMPT
Fri Oct 14 05:14:18 UTC 2022 aarch64 Android
```

## CI: building and releasing every arch

Three workflows, all Android/Termux-specific:

- **`build-native.yml`** — matrix build across `aarch64`, `arm`, `i686`,
  `x86_64` using Termux's package builder. Runs on manual dispatch or as
  a reusable workflow. Uploads one `native-<arch>` artifact per arch
  (`.so` + generated `meta.json`).
- **`release.yml`** — on a `v*` tag push (or manual dispatch), calls
  `build-native.yml`, drops every arch's output into
  `src/psutil/_native/<arch>/`, builds the wheel + sdist, verifies via
  `unzip -l` that all four arches actually landed inside the wheel,
  publishes both as GitHub Release assets, then publishes the same
  wheel + sdist to **PyPI** (tag pushes only, via PyPI Trusted
  Publishing — no API token stored in the repo).

To produce a real multi-arch release:

```bash
git push origin main
git tag v7.2.4 && git push origin v7.2.4
# Actions tab -> release -> wait -> GitHub Release + PyPI both updated
```

One-time PyPI setup (before the first tag push):

1. In this repo's Settings → Environments, create an environment named
   `pypi` (matches `environment: pypi` in `release.yml`'s `publish-pypi`
   job — Trusted Publishing is scoped to it).
2. On PyPI — https://pypi.org/manage/project/psutil-android/settings/publishing/
   for an existing project, or https://pypi.org/manage/account/publishing/
   if `psutil-android` hasn't been published yet — add a Trusted
   Publisher with:
   - Owner: `cumulus13`, Repository: `psutil-android`
   - Workflow: `release.yml`
   - Environment name: `pypi`

No secret needed after that — PyPI trusts the GitHub Actions OIDC token
scoped to that environment.

## Install

From PyPI:
```bash
pip install psutil-android
```

From a downloaded wheel or the release assets:
```bash
pip install psutil_android-7.2.4-py3-none-any.whl
```

Either way it installs as the `psutil` package name — don't install
alongside real `psutil` in the same environment.

## Usage

```python
import psutil
psutil.cpu_percent(interval=1)
psutil.virtual_memory()
psutil.disk_partitions()
```

## Provenance

This is Giampaolo Rodola's `psutil` (BSD-3-Clause, see `LICENSE`),
unmodified at the Python level. There is no dedicated upstream "psutil
for Android" project — Android support has been an open, unresolved
request on `giampaolo/psutil` for years (issues #913, #2611, #2743).
This package fills that gap for Termux users.

## License

BSD 3-Clause, inherited from upstream `psutil`. See `LICENSE`.

## 👤 Maintainer
        
[Hadi Cahyadi](mailto:cumulus13@gmail.com)
    

[![Buy Me a Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/cumulus13)

[![Donate via Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/cumulus13)
 
[Support me on Patreon](https://www.patreon.com/cumulus13)
