AGENT SKILL

python-tool-install

Use when installing Python packages, CLIs, or ML tools.

License 许可
MIT
最近更新
2026-08-16
Stars
★ 0
Forks
0

01 前言 Front Matter

name
python-tool-install
author
hermes
license
MIT
version
1.0.0
metadata
{ "hermes": { "tags": [ "python", "pip", "uv", "venv", "torch", "install", "devops" ], "related_skills": [ "linux-app-install", "python-cli-tools" ] } }
description
Use when installing Python packages, CLIs, or ML tools.

02 资源文件 1

03 SKILL.md 正文

Python Tool Install (pip/uv)

Install Python packages, CLI tools, and ML tooling on Ibrahim's Linux box reliably. Machine quirks (PYTHONPATH hijack, no-pip uv venvs, tight disk, conda stderr noise) break naive installs; follow this workflow instead.

When to use

  • Installing a PyPI package or CLI (the pip install / uv tool install territory)
  • Installing ML tools that pull torch/tensorflow
  • Setting up a project venv that needs isolation from the Hermes venv

Workflow

  1. Check disk first. df -h /home/cybertron. Torch-based installs need ~2-5 GB free. If under ~5 GB: remove dead ~/Downloads/*.crdownload (incomplete Chrome downloads — can be multi-GB), then rm -rf ~/.cache/uv ~/.cache/pip (rebuildable, ~1.5 GB).
  2. Create the venv — uv venvs have NO pip, so plan for uv pip: uv venv --python 3.12 ~/.venvs/<name> — uses /usr/bin/python3.12 and avoids probing the broken conda env.
  3. If the tool needs torch, install CPU torch FIRST, alone: env -u PYTHONPATH uv pip install --python ~/.venvs/<name>/bin/python --index-url https://download.pytorch.org/whl/cpu torch Default PyPI torch pulls ~3 GB of nvidia-* CUDA wheels; the CPU index does not.
  4. Install the actual package: env -u PYTHONPATH uv pip install --python ~/.venvs/<name>/bin/python <pkg>
  5. Expose a wrapper in ~/.local/bin (already in PATH) that clears the PYTHONPATH hijack:
    #!/usr/bin/env bash
    exec env -u PYTHONPATH /home/cybertron/.venvs/<name>/bin/<console-script> "$@"
    
    chmod +x ~/.local/bin/<name>
  6. Verify with a real run. --help proves it loads; for ML tools run an actual small generation/inference and validate the artifact (file type, duration, size). Don't stop at import success.

Pitfalls

  • uv venvs have no pip. python -m pip fails with "No module named pip" (the only reason it sometimes appears to work is the PYTHONPATH-hijacked Hermes venv providing pip — fragile, never rely on it). Always use uv pip install --python <venv>/bin/python.
  • Default PyPI torch = CUDA wheels (nvidia-cusparselt/cusparse/cupti, ~3 GB, and they failed to resolve mid-install on this box). Install CPU torch from the pytorch CPU index before anything else.
  • UV_INDEX_URL alone breaks resolution for non-torch packages (they're not on the CPU index). Env-var index combos (UV_INDEX_URL + UV_EXTRA_INDEX_URL) still pulled CUDA wheels in testing — don't trust them; use the two-step explicit approach above.
  • Piping installs to tail masks the real exit code (tail exits 0 even when the install failed). Redirect to a log file (> /tmp/x.log 2>&1), inspect the log, and check the exit code of the actual command (background
    • process wait reports it).
  • PYTHONPATH hijack: this box's PYTHONPATH points at the Hermes venv. Without env -u PYTHONPATH, cross-venv imports break with ImportError: numpy._core._multiarray_umath / cp311-vs-cp312 .so mismatch. Always env -u PYTHONPATH for the venv's own python/uv.
  • Conda crash dump noise: a broken conda init hook prints a full conda error report on EVERY terminal command's stderr. It is noise — read the actual command log, not the conda dump.
  • First run downloads model weights to ~/.cache/huggingface (HF_TOKEN optional — only rate limits). Budget time and disk for it.

Support files

  • references/pocket-tts-install.md — pocket-tts (kyutai-labs) specifics: CLI, voices, languages, venv/wrapper locations, verified commands.

04 同仓库更多 Skills