---

name: installation-backends description: "Install, build, verify, select, and troubleshoot DeePMD-kit backend variants safely." disable-model-invocation: true metadata: disco-role: operating license: LGPL 3.0

DeePMD-kit Installation and Backends

Use this sub-skill when the task is about installing DeePMD-kit, choosing a package variant, selecting a runtime backend, validating the dp command, or diagnosing backend/build failures before training or inference work begins.

Scope

This sub-skill covers:

• Choosing between pip, conda, Docker, offline installers, and source builds.
• Installing Python 3.10+ environments for TensorFlow, PyTorch, JAX, and Paddle backends.
• Selecting CLI backend aliases such as --tf, --pt, --jax, --pd, --pt-expt, and --backend ....
• Planning source builds with DP_VARIANT, backend enable flags, framework roots, CUDA/ROCM roots, LAMMPS, and i-PI toggles.
• Running safe validation checks: dp -h, dp --version, backend help, Python imports, and bundled environment checks.
• Troubleshooting missing backends, Python/platform mismatches, CUDA/toolkit issues, ABI roots, stale builds, and optional integration toggles.

Do not use this sub-skill for:

• Training input authoring or optimizer/model selection; route to ../training-models/SKILL.md.
• Data system schemas, type maps, or neighbor-stat interpretation; route to ../data-config/SKILL.md.
• Running inference, dp test, model conversion, compression, or model deviation workflows; route to ../inference-model-ops/SKILL.md.
• LAMMPS, i-PI, C API, C++ API, or Node API implementation details; route to ../integrations-development/SKILL.md.

First Decision: Install Path

1. If the user wants the simplest complete runtime with dp, LAMMPS, and MPI tools, prefer conda-forge unless they explicitly need pip wheels.
2. If the user only needs Python workflows, choose pip and install exactly the backend family they need.
3. If the platform is unsupported by wheels or the user needs ROCM, custom CUDA, custom TensorFlow/PyTorch roots, or integration toggles, plan a source build.
4. If the user needs a reproducible prebuilt shell runtime without changing an existing environment, use Docker or offline installers.
5. If the user reports a failure, validate Python, package import, dp, and backend modules before recommending a reinstall.

Read references/install-backend-reference.md for the full decision tree, backend matrix, source-build environment variables, and command examples.

Backend Selection Rules

• DeePMD-kit imports as Python package deepmd; the distribution name is deepmd-kit.
• The dp CLI defaults to the TensorFlow backend unless DP_BACKEND or a backend flag overrides it.
• Training and freezing commands should pass explicit backend flags when the desired backend is not TensorFlow.
• Supported parser aliases include tensorflow/tf, pytorch/pt, jax, paddle/pd, and pytorch-exportable/pt-expt.
• Use dp --backend <name> -h or aliases such as dp --pt -h to confirm the CLI recognizes a backend before deeper debugging.
• Model-file suffixes help inference pick a backend, but install diagnosis should still confirm that the corresponding backend module is importable.

Typical backend choices:

• TensorFlow: default CLI backend; .pb frozen models and TensorFlow checkpoints; install tensorflow or tensorflow-cpu as appropriate.
• PyTorch: use dp --pt; .pth frozen models and .pt checkpoints; install torch; custom C++ OPs require source-build opt-in.
• JAX: use dp --jax; install JAX stack; exported .savedmodel usage also needs TensorFlow support.
• Paddle: use dp --pd; install paddlepaddle or paddlepaddle-gpu; frozen model output uses paired graph/parameter files.
• PyTorch exportable: use --pt-expt or --backend pytorch-exportable only for workflows that explicitly target exportable/AOT PyTorch behavior.

Safe Validation Workflow

When a user asks whether an install is usable, run the least invasive checks first:

python --version
python -c "import deepmd; print('deepmd import ok')"
dp --version
dp -h
dp --tf -h
dp --pt -h

Then run the bundled helper from this sub-skill, choosing backend checks that match the user's intended model family:

python scripts/check_deepmd_environment.py --backend tensorflow
python scripts/check_deepmd_environment.py --backend pytorch --check-backend-help
python scripts/check_deepmd_environment.py --backend all --strict

Use --module <python-module> for a direct module availability check when the backend package has a nonstandard import name or the user is debugging optional dependencies.

Pip Install Patterns

Use pip when the user wants a Python environment and accepts backend-specific wheels:

• TensorFlow CPU: install deepmd-kit[cpu].
• TensorFlow GPU on CUDA 12: install deepmd-kit[gpu,cu12] when CUDA toolkit/cuDNN wheels are needed.
• PyTorch CPU: install CPU torch first from the PyTorch CPU wheel index, then install deepmd-kit.
• PyTorch GPU: install a PyTorch wheel compatible with the user's CUDA/driver stack, then install deepmd-kit.
• JAX CPU: install deepmd-kit[jax].
• JAX CUDA: install deepmd-kit[jax] plus a CUDA-enabled JAX wheel matching the machine.
• Paddle CPU/GPU: install the correct Paddle wheel first, then install deepmd-kit.
• LAMMPS or i-PI extras: add only when integration commands are required, and route detailed integration setup to ../integrations-development/SKILL.md.

Keep backend installs minimal. Do not install every heavy backend unless the user explicitly needs multi-backend compatibility.

Conda, Docker, and Offline Packages

Choose conda-forge when the user wants solver-managed binary compatibility across Python, MPI, LAMMPS, and backend libraries. It is often the safest route for maintainers who need command-line tools plus compiled integrations.

Choose Docker when the user wants to avoid mutating host environments or needs a quick CPU/GPU runtime image.

Choose offline installers when the user has restricted network access and can satisfy runtime platform requirements. Offline and conda packages require GNU C Library 2.17 or newer; pip wheels may require newer glibc on some Linux variants.

For GPU packages, confirm the NVIDIA driver supports the package CUDA minor version. A toolkit installed in the environment does not replace the need for a compatible driver at runtime.

Source Build Router

Use source builds only when prebuilt packages do not meet the user's target:

• Unsupported platform or wheel tag.
• Need ROCM support.
• Need custom CUDA toolkit discovery.
• Need to compile against already installed TensorFlow or PyTorch libraries.
• Need C++ interface, LAMMPS plugin/version integration, or i-PI entry points.
• Need custom PyTorch C++ OPs.

Common Python-package source-build controls:

• DP_VARIANT=cpu|cuda|rocm chooses CPU, CUDA, or ROCM build mode.
• DP_ENABLE_TENSORFLOW=1|0 enables or disables TensorFlow build support; default is enabled.
• DP_ENABLE_PYTORCH=1|0 enables or disables custom PyTorch C++ OPs; default is disabled.
• TENSORFLOW_ROOT points to a TensorFlow Python-library root when isolated build discovery is insufficient.
• PYTORCH_ROOT points to a PyTorch Python-library root when isolated build discovery is insufficient.
• CUDAToolkit_ROOT points to CUDA toolkit discovery for CUDA source builds.
• ROCM_ROOT or ROCM_PATH points to ROCM discovery for ROCM source builds.
• DP_ENABLE_IPI=1 requests i-PI entry point support.
• DP_LAMMPS_VERSION=<version> requests LAMMPS-version-aware C++ interface build behavior.

For CPU-only development installs that avoid heavy custom OPs, install the chosen Python backend first, keep DP_VARIANT=cpu, disable backend C++ OPs that are not needed, and validate deepmd import plus dp -h before attempting training or inference.

Troubleshooting Router

Read references/troubleshooting.md when any of these appear:

• ModuleNotFoundError for tensorflow, torch, jax, or paddle.
• dp --pt fails while dp --tf works, or a .pth model is opened in a TensorFlow-only environment.
• Python is older than 3.10.
• Package installation downloads unexpectedly large wheels or stalls on backend dependency resolution.
• CUDA is found at build time but not usable at runtime.
• TensorFlow/PyTorch ABI or root discovery fails during source build.
• Repeated source builds keep using stale CMake or build-cache state.
• LAMMPS or i-PI commands are missing after a Python-only install.

Handoff Checklist

Before routing onward to training, data, inference, or integrations, report:

• Installation method and backend family selected.
• Python version and whether import deepmd passes.
• Whether dp --version and dp -h pass.
• Which backend modules were checked and whether each is importable.
• Any source-build environment variables the user must set.
• Any remaining platform, CUDA, ABI, LAMMPS, or i-PI risk.