Module environment 

Environment normalization, home directory resolution, and Python interpreter discovery.

Provides:

• Home directory resolution with sudo context handling (VAL-PLAT-017)
• .mlstack_env normalization producing consistent, idempotent environment (VAL-PLAT-018)
• Python interpreter discovery across venvs, conda, and system paths (VAL-PLAT-020)

Sudo Context

When running under sudo, the real user’s home directory is resolved via:

1. MLSTACK_USER_HOME env var
2. $HOME (if not /root)
3. /etc/passwd lookup for SUDO_USER / USER / LOGNAME

Python Discovery Priority

1. MLSTACK_PYTHON_BIN / UV_PYTHON env vars
2. Active virtualenv (VIRTUAL_ENV)
3. Conda environments
4. System Python (/usr/bin/python3, etc.)
5. Component venvs (~/rocm_venv/bin/python)

.mlstack_env Normalization

The env file is idempotent: running normalization twice produces the same output as running it once. Duplicate PATH/LD_LIBRARY_PATH entries are removed, and all required variables are present.

Enums

EnvUpdateResult

Result of .mlstack_env normalization.

Functions

command_on_path

Is cmd executable found on PATH? (Dependency-free; does not spawn.)

create_global_env

Create the managed global environment at ~/.mlstack/global/.

dedup_path_var

Deduplicate colon-separated path entries.

ensure_global_venv

Create the managed global venv at ~/.mlstack/global/ if it does not yet exist, using bootstrap_python (a discovered system/uv interpreter) as the base. Returns the path to the global venv’s python.

ensure_mlstack_dirs

Ensure the ~/.mlstack/ root and its standard subdirs exist.

ensure_named_venv

Create the managed NAMED env at ~/.mlstack/envs/<name>/ if absent (Tenet 1: install-to-env isolation). Returns the path to its python.

generate_env_file

Generate a new .mlstack_env file from scratch.

lookup_home_from_passwd

Look up a user’s home directory from /etc/passwd.

mlstack_cache_dir

The cache directory: ~/.mlstack/cache/.

mlstack_env_dir

A specific named env: ~/.mlstack/envs/<name>/.

mlstack_envs_dir

The named-envs directory: ~/.mlstack/envs/.

mlstack_global_dir

The managed global default environment: ~/.mlstack/global/.

mlstack_global_python

The Python binary of the managed global env: ~/.mlstack/global/bin/python.

mlstack_logs_dir

The logs directory: ~/.mlstack/logs/.

mlstack_root

The single ML Stack root directory: ~/.mlstack/.

mlstack_triton_dir

The triton home directory: ~/.mlstack/triton/.

normalize_env_contents

Normalize the contents of a .mlstack_env file.

normalize_mlstack_env

Normalize the .mlstack_env file in the user’s home directory.

offer_global_prepend

Offer to prepend the global env to the user’s shell rc.

offer_mlstack_env_source

Idempotently append a source ~/.mlstack_env line to ~/.bashrc and ~/.zshrc so the device-filtered ROCm env (iGPUs excluded) is auto-sourced on every POSIX shell launch — the “persistent env” the Global install option promises. Fish is NOT handled here: it auto-loads the conf.d/mlstack_env.fish written by ensure_mlstack_env.

python_interpreters

Discover Python interpreter paths in priority order, deduplicated.

python_interpreters_for_home

Discover Python interpreters for a given home directory (testable).

resolve_canonical_python_bin

Resolve the canonical Python binary path — the single interpreter ALL ML components install into.

resolve_managed_python

Resolve a managed Python interpreter (≤3.13, prefer 3.12) via backend.

resolve_user_home

Resolve the real user’s home directory, handling sudo context.

write_activate_snippets

Write activation snippets to ~/.mlstack/global/.