Skip to content

fix(termux): align manual psutil install with supported installer - #44390

Open
lifuyue wants to merge 1 commit into
NousResearch:mainfrom
lifuyue:fuyue/fix-termux-manual-psutil-docs
Open

fix(termux): align manual psutil install with supported installer#44390
lifuyue wants to merge 1 commit into
NousResearch:mainfrom
lifuyue:fuyue/fix-termux-manual-psutil-docs

Conversation

@lifuyue

@lifuyue lifuyue commented Jun 11, 2026

Copy link
Copy Markdown

Problem

The supported Termux installer prebuilds Hermes' Android psutil compatibility shim before installing the Python package, but the documented manual-install path previously went directly to pip install -e '.[termux]'.

On a fresh Android environment, that difference causes the manual path to fail when upstream psutil rejects sys.platform == "android". This PR closes that Termux compatibility gap by aligning the documented manual workflow with the behavior already implemented by the supported installer; it is not only a documentation clarification.

What Changed

  • updates the Termux manual-install guide so fresh Android installs run python scripts/install_psutil_android.py before pip install -e '.[termux]'
  • mirrors the change in the zh-Hans Termux guide
  • adds troubleshooting for jiter / maturin on 32-bit armv8l Termux devices using CARGO_BUILD_TARGET
  • adds regression coverage so both manual guides keep the psutil shim before package installation and retain the 32-bit Rust target guidance

Reproduction

On current main, I reproduced the psutil failure path by extracting psutil 7.2.2 from the pinned sdist and running its metadata step with sys.platform forced to android. The unpatched sdist exits with:

platform android is not supported

Applying Hermes' existing prepare_patched_psutil_sdist() shim moves past that original rejection point. This confirms that the missing shim step in the manual workflow is the broken path reported in #31415.

Validation

scripts/run_tests.sh tests/test_termux_manual_install_docs.py tests/hermes_cli/test_psutil_android_extract.py tests/test_install_sh_termux_network_prereqs.py -- -q
venv/bin/ruff check tests/test_termux_manual_install_docs.py
git diff --check

After rebasing onto the latest main, the focused documentation regression tests pass (2 passed), and the complete PR patch passes git apply --check cleanly against a fresh main worktree.

Fixes #31415

@alt-glitch alt-glitch added type/docs Documentation improvements P3 Low — cosmetic, nice to have labels Jun 11, 2026
@lifuyue

lifuyue commented Jun 12, 2026

Copy link
Copy Markdown
Author

Hi @alt-glitch, sorry for the ping. I saw your triage note on #31415 and used it to keep this PR scoped to the remaining manual-guide gap rather than changing the installer path again.

The PR body already has the reproduction notes and targeted tests, so I will not repeat those here. When you have a chance, would you mind sanity-checking whether this matches the issue scope you called out, or pointing me to a better reviewer for this Termux/install docs follow-up?

Thank you.

@teknium1

Copy link
Copy Markdown
Contributor

Thanks for narrowing this to the remaining manual-install gap. Current main still sends the manual Termux path directly to python -m pip install -e '.[termux]' at website/docs/getting-started/termux.md:105-108, while the supported installer prebuilds the Android psutil shim before pip installation at scripts/install.sh:1378-1395.

The proposed English and zh-Hans documentation updates align the manual path with that implementation, and the added tests assert the important ordering invariant in both guides. The armv8l guidance also reflects the successful workaround recorded in #31415.

For salvage: gh pr diff 44390 | git apply --check --verbose shows a conflict only in the English guide's installer-list hunk because current main added blank lines there; the substantive documentation changes are otherwise localized.

Automated hermes-sweeper review.

@teknium1 teknium1 added sweeper:risk-compatibility Sweeper risk: may break existing users, config, migrations, defaults, or upgrades sweeper:blast-contained Sweeper blast radius: contained — one narrow path / opt-in / few users labels Jul 14, 2026
@lifuyue
lifuyue force-pushed the fuyue/fix-termux-manual-psutil-docs branch from 4a1f9b5 to 3838b69 Compare July 16, 2026 05:54
@lifuyue

lifuyue commented Jul 16, 2026

Copy link
Copy Markdown
Author

Thanks for the review. I’ve rebased the PR onto the latest main, and the patch now passes git apply --check cleanly for all three files. The targeted documentation tests also pass (2 passed). The changes remain scoped to the Termux manual-install documentation gap.

@lifuyue lifuyue changed the title docs: fix Termux manual psutil install steps fix(termux): align manual psutil install with supported installer Jul 16, 2026
@teknium1 teknium1 added the area/install-update Installer, updater, packaging, wheels, doctor label Jul 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/install-update Installer, updater, packaging, wheels, doctor P3 Low — cosmetic, nice to have sweeper:blast-contained Sweeper blast radius: contained — one narrow path / opt-in / few users sweeper:risk-compatibility Sweeper risk: may break existing users, config, migrations, defaults, or upgrades type/docs Documentation improvements

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Setup]: Failed to install on Android with termux, reporting failed to build psutil

3 participants