Site Python extras on EESSI

Turn a PyPI package or requirements.txt into an easyconfig that installs on top of an EasyBuild robot. Inspect records easyblock = PythonBundle, because ingest does not yet know whether the package brings extensions. A plan of one package emits PythonPackage with its own sources and does not write exts_list. Requirements the robot already provides become dependencies on the providing bundle (soupsieve via Python-bundle-PyPI, numpy via SciPy-bundle). A plan that still has leftovers emits a PythonBundle and keeps only those leftovers in exts_list.

Do not pip install --target and prepend PYTHONPATH. That shadows toolchain-built extensions and has no claim on the European Environment for Scientific Software Installations (EESSI) compat layer.

Inputs

  1. Warehouse-shaped JSON (info + urls) or a requirements.txt;

  2. the EESSI robot tree (or a fixture that mirrors its provides), passed as --easyconfigs. It is the easyconfigs directory bundled with EESSI’s EasyBuild: $EBROOTEASYBUILD/easybuild/easyconfigs after loading EESSI’s EasyBuild module;

  3. a stack policy that locks Python, SciPy-bundle, and Python-bundle-PyPI to the versions in the robot. See examples/stacks/eessi-python-extras.toml.

Inspect does not need a robot. Plan does.

Inspect

eb-stack package inspect \
  --source fixtures/foreign_ingest/pypi_bs4/pypi.json \
  --format pypi \
  --toolchain GCCcore/15.2.0 \
  --out-dir /tmp/bs4-inspect

package.plan.json has origin = pypi and easyblock = PythonBundle. Optional extras (extra ==) become residuals and are not solved.

A requirements.txt is also accepted. The first spec is the root package; later specs are additional run dependencies.

Plan

Source env.sh from scripts/fetch-upstream-trees.sh first. EB_EASYCONFIGS is the develop easyconfigs tree.

Pick the toolchain the way EESSI does. A pure-Python package goes on GCCcore, where EESSI 2026.06 installs Python, Python-bundle-PyPI and BeautifulSoup, so the bs4 plan uses GCCcore/15.2.0 and examples/stacks/eessi-python-gcccore.toml. A package that needs numpy needs SciPy-bundle, which EESSI installs on gfbf/2026.1; the numpy example below uses foss/2026.1, which includes it, and examples/stacks/eessi-python-extras.toml. The policy’s toolchain must be the plan’s --toolchain.

eb-stack package plan \
  --source fixtures/foreign_ingest/pypi_bs4/pypi.json \
  --format pypi \
  --toolchain GCCcore/15.2.0 \
  --easyconfigs fixtures/foreign_ingest/pypi_bs4/robot \
  --stack-policy examples/stacks/eessi-python-gcccore.toml \
  --out-dir /tmp/eb-stack/bundles/bs4

The lock collapses soupsieve to Python-bundle-PyPI. The emitted recipe is PythonPackage, depends on Python 3.14.2 and Python-bundle-PyPI 2026.04, and has no exts_list. The checksum is the one in the fixture. The plan’s easyblock stays PythonBundle; that class is what a multi-package overlay emits. A PythonBundle recipe is for a set installed together, not for a single package.

Against easybuild-easyconfigs develop 981d2123dd, with --easyconfigs "$EB_EASYCONFIGS" after sourcing env.sh, the same package is already provided and the command does not emit a recipe. The manifest residual is:

beautifulsoup4 4.12.3 is already provided by BeautifulSoup 4.14.3 (beautifulsoup4 4.14.3); do not emit a pip overlay

The evidence path is b/BeautifulSoup/BeautifulSoup-4.14.3-GCCcore-15.2.0.eb. The extra-only lxml requirement stays a parse residual.

eb-stack package plan \
  --source fixtures/foreign_ingest/pypi_numpy/numpy.json \
  --format pypi \
  --toolchain foss/2026.1 \
  --easyconfigs fixtures/foreign_ingest/pypi_numpy/robot \
  --stack-policy examples/stacks/eessi-python-extras.toml \
  --out-dir /tmp/eb-stack/bundles/numpy

Asking for numpy against a robot that already provides it writes no recipe. package.plan.json has an already-provided residual: numpy 2.5.2 is already provided by SciPy-bundle 2025.06 (numpy 2.3.1). A recipe that depends on numpy lists SciPy-bundle, not a pip numpy. If the robot has no SciPy-bundle / PyTorch, the plan refuses rather than emitting a wheel overlay.

A leftover that is not in EasyBuild yet (eon-akmc) keeps unsatisfied PyPI run dependencies in the same exts_list. numpy still maps to SciPy-bundle. A maturin/PyO3 leftover such as readcon is closed from a Cargo source root (--cargo-source / kind = "cargo") into a companion PythonPackage (implicit Rust / maturin / binutils) instead of a pip extension. Pass the crate metadata next to the PyPI plan; do not pip install the crate into the overlay.

Resolvo picks every robot-provided name. Extra site packages that Warehouse omits (measured PyYAML for import eon) go in the ingest as a second Warehouse object in a JSON array, or as a later requirements.txt line. A registry name (--source eon-akmc) fetches Warehouse once and writes ingest/pypi/<name>-<version>.json. Replan from that dump; the Boolean satisfiability (SAT) solve does not hit the network. Meson wrap natives come from subprojects/*.wrap in the sdist tree next to the dump (or from build_system.requires). Do not edit the emitted .eb to add those names: put the modules in --easyconfigs and let the lock select them. An undeclared import is a residual, not a silent SAT edge. A PEP 518 build_system block with build-backend = mesonpy adds the listed build requirements and emits wrap_mode=default plus the same cargo-on-EESSI isolation prelude used by Cargo leftovers: drop host rustc wrappers, set LINKER="$CC" (an empty CC becomes gcc, and the value is not evaluated), put the EESSI compat ld on PATH, and point RUSTFLAGS -B at that ld. The cargo target triple and compat arch come from the build host (rustc -vV, uname -m), not from a plan-time x8664literal. Hatchling and meson-python already on Python-bundle-PyPI stay modules; they are not pip extras.

Dependencies that state no version

A Python project routinely requires another package with no version. An exts_list entry still needs one, so planning stops and asks for an index. On this side the index is a pinned requirements file, matching what pip freeze writes:

pip freeze > constraints.txt
eb-stack package plan ... --package-index constraints.txt

One name==version per line; comments and blank lines are ignored, and a line that names a range rather than a version supplies nothing, since a range is not a version. The same flag takes a Comprehensive R Archive Network (CRAN) PACKAGES file for the R side; the format is detected from the content.

Install with the local target

Plan on the host. Install through campaign run:

scripts/fetch-upstream-trees.sh
set -a
source "${EB_UPSTREAM_CACHE:-$HOME/.cache/eb-stack/upstream}/env.sh"
set +a
mkdir -p /tmp/eb-stack/robot /tmp/eb-stack/bundles
rsync -a "$EB_EASYCONFIGS"/ \
  /tmp/eb-stack/robot/

podman build -t eb-stack-rocky9 \
  -f skills/new-package/container/rocky9/Containerfile \
  skills/new-package/container/rocky9

eb-stack campaign run \
  --bundle /tmp/eb-stack/bundles/bs4 \
  --config examples/targets/local-podman.toml \
  --target local-rocky9 \
  --state /tmp/eb-stack/bundles/bs4.campaign.json

examples/targets/eessi-extend.toml is the target whose runtime command is eessi_container.sh. The local target above is the one this checkout runs. That EESSI target execs eb-local with EB_LOCAL_EESSI_EXTEND=1, which loads EESSI-extend and execs eb.

User one-offs stay as python -m venv --system-site-packages on EESSI Python. This workflow is for a shared site or project extra.