Installing GROMACS: Windows (WSL2), Linux and Common GPU Build Problems

Route

Choose an installation route: versions, GPU support and limitations of each

Version information in the table was checked on 2026-10-10. If you need GPU acceleration, only the first two routes give you the current release and your own choice of CUDA version.

Version changes

GROMACS 2026 build requirements, and where copying an old tutorial breaks

Most tutorials online use versions 2018–2021. The table lists requirements and syntax that have changed in 2026.x.

Linux

Building from source on Linux: complete CPU and CUDA commands

GMX_BUILD_OWN_FFTW=ON downloads FFTW 3.3.10 and builds it in single precision with the SIMD options GROMACS recommends. The GROMACS team advises against distribution FFTW packages because they default to double precision and are not compiled with options tuned for GROMACS.

Check two lines in the cmake output: whether the SIMD instruction set matches the CPU (for example AVX2_256 or AVX_512), and, for CUDA builds, "Compiling GROMACS for CUDA architectures: …". When you compile on a login node and run on compute nodes, set -DGMX_SIMD for the compute nodes; a binary built for AVX-512 exits with an illegal instruction on a machine that only supports AVX2. For GPU runs the GROMACS team recommends AVX2_256.

In a CUDA build, nvcc uses CMAKE_CXX_COMPILER as its host compiler. If the system GCC is newer than your CUDA supports, specify an older compiler for both, for example -DCMAKE_C_COMPILER=gcc-12 -DCMAKE_CXX_COMPILER=g++-12, instead of editing CUDA's host_config.h.

# Ubuntu 24.04 (including Ubuntu 24.04 under WSL2); on 22.04 apt ships cmake 3.22, upgrade first with pip install cmake
sudo apt update
sudo apt install -y build-essential cmake wget perl

wget https://ftp.gromacs.org/gromacs/gromacs-2026.4.tar.gz
tar xfz gromacs-2026.4.tar.gz
cd gromacs-2026.4
mkdir build && cd build

cmake .. \
  -DGMX_BUILD_OWN_FFTW=ON \
  -DREGRESSIONTEST_DOWNLOAD=ON \
  -DCMAKE_INSTALL_PREFIX=$HOME/opt/gromacs-2026.4

make -j $(nproc)
make check
make install
echo 'source $HOME/opt/gromacs-2026.4/bin/GMXRC' >> ~/.bashrc
source $HOME/opt/gromacs-2026.4/bin/GMXRC
gmx --version

# Prerequisites: nvcc works (nvcc --version) and nvidia-smi lists the GPU
export PATH=/usr/local/cuda-12.9/bin:$PATH

cd gromacs-2026.4
mkdir build-cuda && cd build-cuda

# CMAKE_CUDA_ARCHITECTURES is the compute capability without the dot:
# RTX 20/T4=75, A100=80, RTX 30/A40=86, RTX 40/L40=89, H100=90, RTX 50=120
# If omitted, every architecture from 50 to 120 that nvcc accepts is built: slower build, larger binary
cmake .. \
  -DGMX_GPU=CUDA \
  -DCUDAToolkit_ROOT=/usr/local/cuda-12.9 \
  -DCMAKE_CUDA_ARCHITECTURES=89 \
  -DGMX_BUILD_OWN_FFTW=ON \
  -DREGRESSIONTEST_DOWNLOAD=ON \
  -DCMAKE_INSTALL_PREFIX=$HOME/opt/gromacs-2026.4-cuda

make -j $(nproc)
make check
make install
source $HOME/opt/gromacs-2026.4-cuda/bin/GMXRC
gmx --version | grep -E "GPU support|CUDA targets|CUDA driver|CUDA runtime|SIMD"

# If the server cannot reach fftw.org or ftp.gromacs.org, download these two files elsewhere and copy them over
#   http://www.fftw.org/fftw-3.3.10.tar.gz
#   https://ftp.gromacs.org/regressiontests/regressiontests-2026.4.tar.gz
tar xfz regressiontests-2026.4.tar.gz -C $HOME/src

cmake .. \
  -DGMX_GPU=CUDA \
  -DGMX_BUILD_OWN_FFTW=ON \
  -DGMX_BUILD_OWN_FFTW_URL=$HOME/src/fftw-3.3.10.tar.gz \
  -DREGRESSIONTEST_PATH=$HOME/src/regressiontests-2026.4 \
  -DCMAKE_INSTALL_PREFIX=$HOME/opt/gromacs-2026.4-cuda

Windows

Building the GPU version under WSL2 on Windows: the driver goes on the Windows side only

After these steps, build with the CUDA commands from the previous section. Known WSL2 limitations: nvidia-smi offers a limited feature set; GPUs cannot be filtered by index number on multi-GPU machines; concurrent CPU/GPU access to the same memory is not supported. Single-GPU GROMACS runs are not affected by these limitations.

# Windows PowerShell (administrator)
wsl --install -d Ubuntu-24.04
wsl --update

# Optional: %UserProfile%\.wslconfig; run wsl --shutdown after editing, then reopen WSL
# [wsl2]
# memory=16GB
# processors=8

# Run inside Ubuntu on WSL; first confirm the Windows driver is passed through
nvidia-smi

wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
# Install only the toolkit metapackage; cuda, cuda-12-9 and cuda-drivers pull in a Linux driver
sudo apt-get install -y cuda-toolkit-12-9

echo 'export PATH=/usr/local/cuda-12.9/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
nvcc --version

# Keep sources and build directories on the Linux file system, not under /mnt/c
mkdir -p ~/src && cd ~/src

1. 01

   Install or update the NVIDIA driver on Windows

   NVIDIA's WSL guide states this is the only driver you need, and that no Linux display driver should be installed inside WSL. The Windows driver is exposed inside WSL2 as libcuda.so, and nvidia-smi lives in /usr/lib/wsl/lib. The CUDA Version shown at the top right of nvidia-smi inside WSL should be at least the toolkit version you plan to install.

2. 02

   Install WSL2 and Ubuntu 24.04

   CUDA is supported on WSL 2 only, not WSL 1. Ubuntu 24.04 ships CMake 3.28.3 and GCC 13.2 via apt, which meet GROMACS 2026's requirements, so you can skip a manual CMake upgrade.

3. 03

   Install only the cuda-toolkit-12-x metapackage

   Use NVIDIA's wsl-ubuntu repository. The cuda, cuda-12-x and cuda-drivers metapackages install a Linux driver that overrides the WSL libcuda mapping and leaves the GPU unusable. CUDA 12.9 can build for compute capability 5.0 through 12.0, covering the RTX 50 series as well as the GTX 10 series.

4. 04

   Keep sources and build directories under ~

   Microsoft recommends storing files under /home/<user> when working from a Linux command line, not under /mnt/c. Building under /mnt/c is slow, and a GROMACS forum user building there got "Clock skew detected" warnings.

5. 05

   Lower the parallelism if the build runs out of memory

   By default WSL2 gets only 50% of Windows memory. If make -j stops with "c++: fatal error: Killed signal terminated program cc1plus", memory ran out; lower the -j value, or raise memory in .wslconfig and run wsl --shutdown.

conda

Installing with conda: the commands work, but know these four limitations

# linux-64 only (including WSL2). The CUDA build needs a driver that supports CUDA 12.9
conda create -n gmx -c conda-forge "gromacs=2026.3=nompi_cuda*"
conda activate gmx
gmx --version | grep -E "GPU support|SIMD"

# CPU/OpenCL build
# conda create -n gmx-cpu -c conda-forge "gromacs=2026.3=nompi_h*"

# ~/.condarc (conda-forge setup from the TUNA help page; run conda clean -i afterwards)
# channels:
#   - conda-forge
#   - nodefaults
# show_channel_urls: true
# custom_channels:
#   conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
conda clean -i
conda create -n gmx -c conda-forge "gromacs=2026.3=nompi_cuda*"

# With mamba, use mirrored_channels instead
# channels:
#   - conda-forge
# mirrored_channels:
#   conda-forge:
#     - https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge

# For source builds, upgrade CMake with pip (3.28 or newer is required)
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "cmake>=3.28"

Testing

make check failures: which are acceptable and how to locate the cause

The official installation guide's rule: an individual failed test may be a compiler bug, or a tolerance that is slightly too tight. Inspect the output files the script points to; if the failure is real, rebuild with a newer compiler. If the tests still fail, post on the GROMACS forum with a description of the hardware and the full output of gmx mdrun -version.

The most common case on the GROMACS forum is a GPU build where many tests report Timeout. A developer explained that tests use every core and GPU they detect by default, so they time out when the CPU or GPU is busy with other jobs. In one 2021.1 case, 23 tests timed out with GPU detection enabled and only 1 remained with GMX_DISABLE_GPU_DETECTION=1. If the failures are only timeouts and the CPU-only run passes, confirm the GPU works with the water box self-test in the next section; numerical comparison failures (output shows reference values that do not match the computed ones) should not be ignored.

# Show only the failed tests
make check 2>&1 | tee check.log
grep -A40 "tests FAILED" check.log

# 1. Rule out the GPU: if the CPU run passes and the GPU run times out, the GPU is usually busy
GMX_DISABLE_GPU_DETECTION=1 make check

# 2. On multi-GPU machines, expose a single GPU to the tests
CUDA_VISIBLE_DEVICES=0 make check

# 3. Timeouts on slow machines or under WSL: raise the timeout factor and reconfigure
cmake .. -DGMX_TEST_TIMEOUT_FACTOR=3 && make check

# 4. Rerun a single test with full output
ctest -R MdrunTests --output-on-failure

Errors

Common error lookup table

Verification

After installing, confirm the GPU really does the work

First run gmx --version and check that the GPU support line says CUDA, CUDA targets includes your GPU's architecture, and CUDA driver is not older than CUDA runtime. Builds with the PLUMED interface show its status on the Plumed support line.

Then run a water box. The -nb, -pme and -update options of mdrun all default to auto: if no usable GPU is detected, mdrun silently falls back to the CPU and only runs slower. Request gpu explicitly for the self-test so that an unusable GPU stops the run with an error.

mkdir -p ~/gmx-gpu-test && cd ~/gmx-gpu-test

# 5 nm cubic water box, about 4000 SPC/E waters
gmx solvate -cs spc216.gro -box 5 5 5 -o water.gro
cat > topol.top <<'EOF'
#include "oplsaa.ff/forcefield.itp"
#include "oplsaa.ff/spce.itp"

[ system ]
SPC/E water box

[ molecules ]
EOF
echo "SOL $(grep -c OW water.gro)" >> topol.top

cat > em.mdp <<'EOF'
integrator    = steep
emtol         = 1000
nsteps        = 5000
cutoff-scheme = Verlet
coulombtype   = PME
rcoulomb      = 1.0
rvdw          = 1.0
EOF

cat > md.mdp <<'EOF'
integrator     = md
dt             = 0.002
nsteps         = 25000
cutoff-scheme  = Verlet
coulombtype    = PME
rcoulomb       = 1.0
rvdw           = 1.0
tcoupl         = V-rescale
tc-grps        = System
tau-t          = 0.1
ref-t          = 300
gen-vel        = yes
gen-temp       = 300
constraints    = h-bonds
nstcalcenergy  = 100
nstenergy      = 1000
nstlog         = 5000
EOF

gmx grompp -f em.mdp -c water.gro -p topol.top -o em.tpr
gmx mdrun -s em.tpr -c em.gro -g em.log
gmx grompp -f md.mdp -c em.gro -p topol.top -o md.tpr

# Request gpu explicitly: if no GPU is usable, mdrun stops with an error instead of silently falling back to the CPU
gmx mdrun -s md.tpr -g md.log -nb gpu -pme gpu -update gpu -ntmpi 1

grep -A2 "Mapping of GPU IDs" md.log
grep -E "PP task|PME tasks" md.log
grep "Performance:" md.log

  GPU info:
    Number of GPUs detected: 1
    #0: NVIDIA NVIDIA GeForce RTX 4090, compute cap.: 8.9, ECC:  no, stat: compatible

1 GPU selected for this run.
Mapping of GPU IDs to the 2 GPU tasks in the 1 rank on this node:
  PP:0,PME:0
PP tasks will do non-perturbed short-ranged interactions on the GPU
PP task will update and constrain coordinates on the GPU
PME tasks will do all aspects on the GPU

• stat: compatible: the GPU was recognized and its architecture is compiled in. "not in set of targeted devices" means you need to rebuild for that architecture.
• The Mapping of GPU IDs line lists both PP and PME: both task types run on the GPU. With PP only, PME is computed on the CPU.
• PP task will update and constrain coordinates on the GPU: GPU-resident mode is active. CPU here means the system or settings do not qualify, for example virtual sites, mass or constraint free-energy perturbation, replica exchange, or constraints = all-bonds under domain decomposition.
• A NOTE containing "does not include kernels compiled natively": GPU kernels are JIT-compiled from PTX and may run slower; rebuild with the architecture value given in the log.
• ns/day on the Performance line: compare with a run using -nb cpu -pme cpu -update cpu; on the same system the GPU run should be much faster, and similar numbers mean the GPU did not take part.
• Tested on this page (CPU reference, not GPU speed): the script above with the conda-forge GROMACS 2026.3 CPU build on an Apple M2 (8 cores, other jobs running on the machine at the same time). gmx solvate produced 4,055 water molecules and 12,165 atoms; energy minimization reached Fmax < 1000 in 12 steps; mdrun with -nb gpu stopped with Nonbonded interactions on the GPU were requested with -nb gpu, but the GROMACS binary has been built without GPU support.; with -nb cpu -pme cpu -update cpu -ntmpi 1 the 50 ps run reached 14.4 ns/day under heavy load and 27.8 ns/day at lower load (1-minute load average about 13, -nsteps 10000 -resethway), and md.log showed Using SIMD4xM 4x4 nonbonded short-range kernels with no Mapping of GPU IDs or PP task lines. A GPU build should be much faster on the same system; similar numbers mean the GPU is not doing the work.

Run options

GPU acceleration commands: setting -nb, -pme, -update, -ntmpi and -ntomp

In GPU-resident mode (-update gpu), the GROMACS team recommends setting nstcalcenergy and the temperature and pressure coupling intervals to at least 50–100 steps, because the overhead of frequent virial and energy computation does not show up in the cycle counters of the log. Use constraints = h-bonds as well: it is one of the prerequisites for GPU-resident mode and matches how most force fields were parametrized.

When running several simulations on one GPU without -update gpu and without MPS or MIG, NVIDIA's tests showed no throughput gain. One A100 ran the 24,000-atom RNAse system at 1,083 ns/day and the 96,000-atom ADH system at 378 ns/day (GROMACS 2021.2), which can serve as a reference when estimating the speed of a comparable GPU.

Experience

Community-tested rules of thumb and pitfalls

The following comes from Sobereva's blog (Computational Chemistry Commune) and the GROMACS forum; most points can be checked against first-hand documentation.

PLUMED

GROMACS + PLUMED: since 2025, start with the native interface and patch only for specific features

Since 2025 the GROMACS source includes the PLUMED 2.10 interface, which the GROMACS documentation describes as compatible with any PLUMED version. It is enabled by default on non-Windows systems (GMX_USE_PLUMED=AUTO); building only requires dlopen from the system, and PLUMED need not be installed beforehand. At run time point the PLUMED_KERNEL environment variable to the kernel library and add -plumed plumed.dat.

The native interface does not support the ENERGY collective variable, replica exchange or lambda dynamics; PLUMED exits with an error when more than 1 thread-MPI rank is used, so add -ntmpi 1 on a single node and build an MPI version for multiple ranks. In 2026.0–2026.3, MPI-parallel mdrun -plumed aborts at start-up; 2026.4 fixes this.

ENERGY, multiple walkers or OPES multithermal still require the patch. Patches are provided for specific GROMACS versions: PLUMED 2.10.1 (released July 2026) ships patches for gromacs-2022.5, 2023.5, 2024.3 and 2025.0; a gromacs-2026.0 patch currently exists only in PLUMED's development branches. To patch, run plumed patch -p in the GROMACS source root before running cmake; the PLUMED documentation recommends also setting -DGMX_THREAD_MPI=OFF -DGMX_MPI=ON.

The GROMACS documentation names the kernel library libPlumedKernel.so, while PLUMED installs it as libplumedKernel.so by default. Linux file names are case-sensitive, so copying the documentation path verbatim fails to find the file.

# 1. Build PLUMED (no ordering requirement relative to GROMACS)
wget https://github.com/plumed/plumed2/releases/download/v2.10.1/plumed-2.10.1.tgz
tar xzf plumed-2.10.1.tgz && cd plumed-2.10.1
./configure --prefix=$HOME/opt/plumed-2.10.1
make -j $(nproc) && make install

# 2. Force the interface on when building GROMACS 2025/2026 (AUTO only prints a STATUS message and disables the interface when dlopen is missing; ON stops with an error)
cmake .. -DGMX_GPU=CUDA -DGMX_USE_PLUMED=ON -DGMX_BUILD_OWN_FFTW=ON
gmx --version | grep -i plumed

# 3. Point to the kernel library at run time. The real file name is libplumedKernel.so (lowercase p)
export PLUMED_KERNEL=$HOME/opt/plumed-2.10.1/lib/libplumedKernel.so
gmx mdrun -s md.tpr -plumed plumed.dat -ntmpi 1

Agent

Hand this workflow to an agent

Example instruction: "Prepare a GROMACS 2026 GPU environment on one GPU, run a 5 nm water box for 50 ps each with -update gpu and -update cpu, report the ns/day of both, and include the GPU mapping lines from md.log and the gmx --version output."

In an isolated cloud computer, the agent uses the preinstalled GROMACS 2026.3 GPU build, or compiles another version with the commands on this page when needed; rents a GPU for the task; generates topol.top, em.mdp, md.mdp and the tpr files; runs both simulations; extracts ns/day and the GPU mapping lines from the logs; and finally reviews the results adversarially to check that the GPU really took part. The workspace keeps scripts, parameter files, logs and results, and the task keeps running after you shut down your own computer.

You still need to check: that the GROMACS version stated in your paper's methods matches the version actually used; that md.log shows update and PME running where you expect; and the force field, water model and mdp settings of your production system, which are your decisions. A water box self-test does not replace equilibration checks on the production system.