# Quantum ESPRESSO: building the plane-wave DFT suite from source

> Quantum ESPRESSO is a GPL-2.0 suite of Fortran codes for electronic structure calculation, covering ground-state DFT, molecular dynamics, phonons, response functions and many-body perturbation theory, built with either a configure script or CMake. It suits a computational materials scientist who needs the codes compiled locally with a specific MPI toolchain, and it is the wrong tool if you want a packaged installer.

**QEF/q-e** — Mirror of the Quantum ESPRESSO repository. Please do not post Issues or pull requests here. Use gitlab.com/QEF/q-e instead.

- Repository: https://github.com/QEF/q-e
- Stars: 704 · Forks: 331
- Language: Fortran
- License: GPL-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/qef-q-e

## A suite of codes, not a single program

Quantum ESPRESSO is distributed as a suite of codes, and the project expands its own acronym as opEn-Source Package for Research in Electronic Structure, Simulation, and Optimization. The primary language is Fortran, the licence is GPL-2.0, and the default branch in this repository is develop.

The packages are where the scope becomes clear. PWscf handles structural optimisation and molecular dynamics on the electronic ground state with a self-consistent solution of the DFT equations, and it is the code the whole suite is built around. CP is Car-Parrinello molecular dynamics. PHonon computes vibrational and dielectric properties from DFPT, the density-functional perturbation theory, and TD-DFPT gives spectra from time-dependent DFPT. HP calculates Hubbard parameters from DFPT. EPW computes electron-phonon coefficients, carrier transport, phonon-limited superconductivity and phonon-assisted optical processes, and PWCOND covers ballistic transport. XSpectra calculates X-ray absorption spectra, and PWneb finds reaction pathways and transition states with the Nudged Elastic Band method. GWL does many-body perturbation theory in the GW approach using ultra-localised Wannier functions and Lanczos chains, QEHeat computes energy current in insulators for thermal transport within DFT, and KCW implements Koopmans-compliant functionals in a Wannier representation.

That is a wide surface, and it is the reason the build system matters as much as the physics. A user who only needs self-consistent field calculations and structure optimisation is not going to build EPW and GWL, and the Makefile is built to let them build a subset.

The target names are printed by the Makefile itself, which starts with a note that to install Quantum ESPRESSO you type ./configure at the shell prompt and then make with a target. The targets cover pw for the basic code for scf, structure optimisation and MD, ph for phonons with Gamma-only and third-order derivatives, hp, pwcond, neb, pp for postprocessing programs, cp, all_currents for the QEHeat code, tddfpt, gwl, ld1 for pseudopotential generation utilities, xspectra, couple for the library interface for coupling to external codes, epw which also compiles w90, and kcw. There is a pwall target, described as the same as making pw, ph, pp, pwcond and neb together.

## Two build systems, and why the compiler flags matter

The project documents two ways to build, and the choice comes down to how much control you want over the toolchain.

The traditional path is the configure script. Go to the directory where the readme is and run:

```bash
./configure [options]
make all
```

Square brackets in that usage line mean the options are optional, and make alone prints a list of acceptable targets rather than building everything. Parallel compilation is make -jN on N processors, and the resulting binaries are found in bin/.

The CMake path requires version 3.14 or later and looks like this:

```bash
mkdir ./build
cd ./build
cmake -DCMAKE_Fortran_COMPILER=mpif90 -DCMAKE_C_COMPILER=mpicc [-DCMAKE_INSTALL_PREFIX=/path/to/install] ..
make [-jN]
[make install]
```

The documentation is emphatic about one point here. Although CMake has the capability to guess compilers, it is strongly recommended to specify the intended compilers or MPI compiler wrappers as CMAKE_Fortran_COMPILER and CMAKE_C_COMPILER. That recommendation is the whole reason to prefer CMake in a cluster setting: a Fortran compiler that is not the MPI wrapper will build, and then fail or run incorrectly at parallel scale.

Two further differences follow. With CMake, make builds all targets and the binaries are found in build/bin, and if make install is invoked, the CMAKE_INSTALL_PREFIX directory is prepended onto all install directories.

There is also a GPU path, and it is separate. The readme points to a dedicated README_GPU.md file for GPU execution, and the tree contains a devXlib directory of low-level utilities for GPU execution alongside the general documentation.

For general documentation there is the Doc/ directory, package-specific documentation in each package's Doc/ folder, the quantum-espresso.org website, and a wiki page on gitlab for technical documentation aimed at users and developers.

## Libraries pulled out of the code for reuse elsewhere

A large part of the distribution has been isolated and partially encapsulated with the intention of releasing it for use in other codes, and that is arguably the most transferable part of the project for a group with its own numerical code.

UtilXlib handles basic MPI handling, error handling and timing handling. FFTXlib provides parallel, MPI and OpenMP distributed three-dimensional FFTs, and it also does load-balanced distribution of data across processors, for plane waves, G-vectors and real-space grids. LAXlib is parallel distributed dense-matrix diagonalization, using ELPA, SCALapack or a custom algorithm. The KS Solvers package does parallel iterative diagonalization for the Kohn-Sham Hamiltonian, which is represented as an operator, using block Davidson and band-by-band or block conjugate-gradient algorithms. LRlib performs a variety of tasks connected with time-dependent DFPT, and can also be used in connection with many-body perturbation theory. upflib holds pseudopotential-related code, and devXlib collects low-level utilities for GPU execution.

For a computational materials group this matters more than the application codes do. If you already have a code that does plane-wave DFT and you want to swap in a different diagonalization, a different FFT distribution or a different pseudopotential library, these are the components you would replace, and they are separated for exactly that reason.

The pseudopotential side has its own directories in the tree, with PP/ for the pseudopotential tooling and pseudo/ for pseudopotential files, and the ld1 target is the pseudopotential generation utility. The dft-d3/ directory and the XClib/ directory sit alongside them, and the archive/ and external/ directories hold supporting material. There is a test-suite/ directory and a test/ directory, plus a GUI/ directory and a GWW/ directory among the packages, and the COUPLE/ and CPV/ directories for the coupling interface.

## Why this repository is a mirror, and where the real work happens

The repository description is a single sentence and it changes what you should do here: this is a mirror of the Quantum ESPRESSO repository, issues and pull requests should not be posted here, and the place to go is gitlab.com/QEF/q-e.

That is worth taking seriously for anyone evaluating the project. The canonical history, the issue tracker and the review conversation live on GitLab, and this copy on GitHub is a read-only mirror of it. The tree supports that reading. There is a .gitlab-ci.yml along with .gitlab-ci-main.yml and .gitlab-ci-version-consistency.yml for continuous integration, a .gitlab-ci file for the version consistency check, and a .gitmodules file, and the wiki link in the readme points at the gitlab wiki rather than a GitHub one. The old .travis.yml is still in the tree from the era before the migration.

The GitHub presence is still useful for reading and for referencing a specific commit, and the continuous integration configuration is in the repository either way, but a contributor following the readme will end up on GitLab.

On the release side, the tags tell the story of a project on a slow, deliberate version cadence. The recent releases are qe-7.6 on 2026-07-09, qe-7.0 from 2021-12-21 and qe-6.8 from 2021-07-19. The gap between 7.0 and 7.6 is several years, which tells you the versioning is tied to long development cycles rather than to regular patches, and the CI configuration includes a dedicated version consistency check, which suggests the version string is validated across the packages.

The licence is worth stating plainly for a scientific code. All the material in the distribution is free software under the GNU General Public License version 2 or later, so you may redistribute and modify it, and the project says contributions are welcome with a CONTRIBUTING.md file that explains how.

## Where Quantum ESPRESSO is the wrong choice

The first limitation is the build itself. This is a source distribution of Fortran codes that link against MPI, FFT and linear algebra libraries, and there is no packaged installer in this repository. A user without a working MPI toolchain, or without a Fortran compiler matching the code, is not going to get a working pw binary from a download, and the failure surfaces during configure or link rather than at runtime.

The second is the size of the surface. The suite is a large Fortran codebase, the kind where a bad optimisation flag or a mismatched BLAS produces wrong numbers rather than a crash, and where the first successful build for a new user is a genuine project. There is a well-trodden path through the documentation for that, but it is a path, not a double-click.

The third is scope mismatch. Quantum ESPRESSO is a plane-wave DFT code. If your problem is a tight-binding model, a large-scale classical molecular dynamics simulation, a finite element calculation or a quantum chemistry package with a different formalism, this is the wrong suite, and the packages listed here, from PWscf through EPW and GWL, are all in the same family of methods.

The fourth is the mirror situation for contributors. Anyone who intends to file an issue, send a patch or take part in review has to do it on GitLab, and the GitHub copy is not the place where that conversation happens. That is a trivial administrative fact, but it is also a signal about where the project actually lives.

The fifth is the release cadence. With the newest tag at qe-7.6 and the previous two from 2021, a group that needs a bug fix in the current release has to see whether it has been fixed upstream and when. A codebase that is stable, widely used and mature is exactly what a research group wants, and it is also a codebase where the practical question is how quickly fixes propagate, not whether the code is good.

## Conclusion

Quantum ESPRESSO fits a computational materials group that compiles the codes itself, on a cluster with a specific MPI toolchain, or that needs one of the modular libraries such as FFTXlib or LAXlib inside its own code, and the CMake path with explicit compiler flags makes that build reproducible. It is the wrong choice for someone who wants a binary from a package manager, and this particular repository is a mirror, so contributions and issues belong at gitlab.com/QEF/q-e rather than here. Before building, read the general documentation in the Doc/ directory and the package-specific documentation in each package's Doc/ folder, plan the build around a specific core package rather than everything, and note that the last push was on 2026-07-09 with the qe-7.6 tag published the same day.

## FAQ

### How do I build Quantum ESPRESSO from source?

Run ./configure and then make all for the traditional path, or use CMake 3.14 or later with cmake -DCMAKE_Fortran_COMPILER=mpif90 -DCMAKE_C_COMPILER=mpicc .. in a build directory followed by make. The documentation strongly recommends specifying the MPI compiler wrappers explicitly rather than letting CMake guess.

### Which Quantum ESPRESSO packages are there?

PWscf for ground-state DFT, CP for Car-Parrinello molecular dynamics, PHonon and TD-DFPT for vibrational properties and spectra, HP for Hubbard parameters, EPW for electron-phonon coupling and superconductivity, PWCOND for ballistic transport, XSpectra for X-ray absorption, PWneb for reaction paths, GWL for GW many-body perturbation theory, QEHeat for energy current, and KCW for Koopmans functionals.

### Where should I report problems with Quantum ESPRESSO?

Not on this GitHub repository, which is a mirror. Issues and pull requests should go to gitlab.com/QEF/q-e, and the technical documentation wiki is on GitLab as well.

### What modular libraries does Quantum ESPRESSO ship?

UtilXlib for MPI, error and timing handling, FFTXlib for parallel distributed three-dimensional FFTs, LAXlib for parallel dense-matrix diagonalization using ELPA, SCALapack or a custom algorithm, KS Solvers for iterative Kohn-Sham diagonalization, LRlib for time-dependent DFPT tasks, upflib for pseudopotential code, and devXlib for low-level GPU utilities.

### What licence is Quantum ESPRESSO released under?

GNU General Public License version 2 or later. The distribution is free software that may be redistributed and modified under those terms.

## Sources

- [Issues](https://github.com/QEF/q-e/issues)
- [License: GPL-2.0](https://github.com/QEF/q-e/blob/develop/LICENSE)
- [QEF/q-e on GitHub](https://github.com/QEF/q-e)
- [README](https://github.com/QEF/q-e/blob/develop/README.md)
- [Releases](https://github.com/QEF/q-e/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/qef-q-e