module-manager

module-manager deploys versioned Python, binary, shell, and collective CLI environments behind GNU environment modulefiles for Linux/HPC systems.

It writes tools and modulefiles into predictable versioned locations:

/prod/tools/<name>/<version>/bin
/prod/modulefiles/<name>/<version>

The installation prefix and module root must be different directories.

Installation

Install from PyPI:

pip install env-module-manager

Or install as a uv-managed tool:

uv tool install env-module-manager

Quick Start

Deploy a Python CLI with uv tool install:

module-manager deploy-python ruff 0.8.0 \
  --package 'ruff==0.8.0' \
  --default-index https://packages.example/simple \
  --constraints /prod/constraints/runtime.txt \
  --uv-executable /opt/uv/bin/uv \
  --prefix /prod/tools \
  --module-root /prod/modulefiles \
  --execute-install

Set MODULE_MANAGER_UV_EXECUTABLE=/opt/uv/bin/uv to use the same uv path by default.

To expose executable entry points from direct dependencies too, add --with-executables-from=package1,package2. Used without package names, the option reads [project].dependencies from the current directory's pyproject.toml.

Python deployments also pass through uv's --with, --with-requirements, --constraints, --overrides, --lfs, --verbose, --native-tls, and --no-config options. --config-file is accepted as an alias for --uv-config-file.

Deploy a binary:

module-manager deploy-binary ripgrep 14.1.1 \
  --binary ./target/release/rg \
  --prefix /prod/tools \
  --module-root /prod/modulefiles

Add --env NAME=VALUE to any deploy command to export a variable from the generated modulefile. For deploy-env, variables can also be declared in the manifest's [environment] table.

Every completed deployment includes a module-manager.lock.json file with its metadata and generated-file checksums. Use module-manager list --prefix PATH, module-manager show NAME VERSION, and module-manager verify NAME VERSION to inspect recorded deployments and detect missing, modified, or unexpected files.

Generate a constraints file for a Python CLI:

module-manager auto-constraints ruff==0.8.0 --output constraints.txt

Deploy from a direct wheel or Git URL:

module-manager deploy-python my-tool 1.0.0 \
  --package 'my-tool @ file:///prod/wheels/my_tool-1.0.0-py3-none-any.whl' \
  --prefix /prod/tools \
  --module-root /prod/modulefiles \
  --execute-install

Deploy a shell script:

module-manager deploy-script my-tool 1.0.0 \
  --script ./scripts/my-tool \
  --prefix /prod/tools \
  --module-root /prod/modulefiles

Deploy a collective environment from a TOML manifest:

module-manager deploy-env --file dev-tools.toml --dry-run
module-manager deploy-env --file dev-tools.toml

Deploying an existing name and version is refused by default. Add --force to replace that deployment deliberately.

Use the generated module:

module use /prod/modulefiles
module load ruff
ruff --version

Deployments make the deployed version the module default. Add --no-default when you want to write the versioned modulefile without changing the default.

Remove a deployed version:

module-manager uninstall ruff 0.8.0 \
  --prefix /prod/tools \
  --module-root /prod/modulefiles

Documentation

Read the full documentation on Read the Docs.