---

name: install-and-environment description: "Install, inspect, and troubleshoot Megatron Core and Megatron-LM runtime environments." metadata: disco-role: operating disable-model-invocation: true license: NOASSERTION

install-and-environment

Use this sub-skill when the task is about getting Megatron Core importable, choosing a Megatron-LM environment, checking CUDA readiness, or diagnosing dependency/build problems before training or inference.

Read first

• For install modes, Python/CUDA/package variants, and optional dependency groups, read references/install-reference.md.
• For import failures, CPU-only Torch, CUDA/driver mismatch, build OOM, or optional TransformerEngine/Apex/ModelOpt warnings, read references/troubleshooting.md.
• To run a safe local probe, use scripts/check_megatron_environment.py. It checks package metadata, imports, optional modules, and CUDA availability without starting training.

Quick route

User asks about	Do this
"How do I install Megatron Core?"	Recommend PyPI or source install from references/install-reference.md, then run the bundled environment probe.
"Which extras do I need?"	Map the workflow: base import needs only megatron-core; training data/tokenizers need [training]; TE/ModelOpt/Mamba/FP8 paths require narrower optional extras or container-provided deps.
"CUDA is not available"	Check Torch wheel CUDA tag, driver max CUDA, device visibility, and container GPU passthrough; do not treat CPU import as GPU verification.
"TransformerEngine/Apex warnings appear"	Distinguish fallback-safe CPU/local paths from workflows that truly require TE/Apex/ModelOpt kernels.
"Editable install failed"	Check Python version, build dependencies, MAX_JOBS, and whether the user is trying to build broad dev extras outside the recommended container.

Minimal verification workflow

1. Identify whether the task is package use, repo development, or large-scale CUDA training.

2. Install the smallest dependency set that covers that task. Do not install all optional groups by default.

3. Run:

   python scripts/check_megatron_environment.py --check-cuda --optional transformer_engine apex modelopt mamba_ssm
   

   Run the bundled script from this skill directory or copy it into a scratch area. It prints JSON-like facts and exits nonzero only when explicitly required checks fail.

4. If the task will run real training/inference, continue to the owning sub-skill:

   • ../training-cli-and-data/SKILL.md for training/data/launches.
   • ../inference-and-serving/SKILL.md for inference/server workflows.
   • ../core-models-and-parallelism/SKILL.md for model/parallelism API choices.

Environment facts to preserve in answers

• Current Megatron-LM metadata packages the public distribution as megatron-core and imports as megatron.core / megatron.training.
• Current metadata requires Python >=3.12 and base dependencies torch>=2.6.0, numpy, and packaging.
• The package is CUDA-centered. A CPU import check is useful, but it does not validate distributed training, NCCL, FP8, TransformerEngine kernels, or inference CUDA graphs.
• Broad development installs are heavy because optional packages may compile CUDA extensions. Prefer the NGC/container path for full dev, TE, ModelOpt, Mamba, FlashMLA, and DeepGEMM workflows.
• If build jobs exhaust memory, retry with a conservative MAX_JOBS, for example MAX_JOBS=4.

Boundaries

• This sub-skill owns environment selection and import/backend diagnosis.
• Use ../training-cli-and-data/SKILL.md for command construction and data preprocessing.
• Use ../testing-ci-and-maintenance/SKILL.md for repo CI containers, uv.lock, lint groups, base image bump PRs, and golden-value workflows.