Installing the Quantum ESPRESSO distribution
How to get the distribution, how to install it, i.e. produce
the executables; what you need for a succesful installation,
and what to do if the installation is NOT successful! Updated March 2018
Requirements for Quantum ESPRESSO installation
Things that you MUST have on your machine:
All hardware is supported, as long as it has what is listed above.
- Unix, or a Unix-like environment
(a shell and the Make utility): Mac OS-X ok, Windows with
- a working fortran compiler compliant with the F2003 standard
(not-so-old compilers, e.g., "gfortran", should do the job)
- a working C compiler ("gcc" is ok)
In order to run in parallel, you MUST have at least one of the following:
Libraries: Quantum ESPRESSO uses and provides a copy of the following external
Things that you SHOULD have on your machine for real-life usage:
- working MPI (Message-passing Interface):
parallel compiler ("mpif90" or similar scripts), MPI libraries,
run-time environment ("mpirun" or similar launchers)
OpenMP-capable compiler and autothreading mathematical libraries
(for multi-core CPUs)
- Fast mathematical libraries
- For parallel execution: fast interprocess communication hardware
- Choose and create a directory where to install Quantum ESPRESSO.
It should be on a file system that
- is local to the PC you are using: sometimes the home directory
in a PC cluster is accessed via the network (NFS). Moving large amount
of data via the network MUST BE AVOIDED.
- has enough disk space and a large enough disk quota: sometimes
the home directory is small, or has a quota enforced.
You will need a few tens of Mb just to compiler the distribution.
- Download in the chosen directory the package q-e-XYZ.tar.gz
The suffix ".gz" means "compressed by gzip" (a free utility
found on most Unix machines).
The suffix ".tar" means "archived by tar" (the standard
Unix command for archiving and retrieving files)
- Uncompress and unpackage the file:
tar -zxvf q-e-XYZ.tar.gz
Some machines may not support the "z" flag (meaning "uncompress
files compressed by gzip"). In this case:
tar -xvf q-e-XYZ.tar
A directory "q-e-XYZ/" will be created, containing many files
and other directories.
- Execute initialization steps, if needed. For instance,
in order to enable the usage of Intel compiler and MKL libraries,
you should set a number of variables; for parallel execution, you
should add a parallel compiler to your path. How to do this depends
on the specific machine. Sometimes one has to use the command "module",
as in the following example:
module load intel/18.0
module load mkl/18.0
- Enter the "q-e-XYZ/" directory and execute "./configure":
"configure" is a wrapper, calling the "install/configure" script,
that tries to guess your machine and to choose compilation and
linking options accordingly. "install/configure" is generated
from "install/configure.ac" using the complex but well-known
Unix utility "autoconf". The result of "configure" is a file
called "make.inc" containing the compilation and linking options.
You may want to have a look at it to verify what "configure" thinks
about your system.
Several options to "configure" may (and sometimes, have to) be specified
If everything is fine you should get a bunch of (mostly obscure
and irrelevant) messages but no error. Read the last lines: you may
need to understand them if something goes wrong at compilation stage,
or if you need to boost performances.
BEWARE: if you have a parallel compiler in you path, "configure"
will choose it. If the parallel and serial compilers do not match,
you may run into trouble (check for the presence of "WARNING"
in the output of "configure"!). You can use "configure" optional
variables F90, MPIF90 to select the compiler you want, and in some
cases, environment variables like OMPI_FC to select the compiler
used in parallel compilation. Use
to produce a serial executable. Use
to produce a parallel executable with OpenMP enabled.
- Compile the packages you need. Let us start from PWscf:
"make" is another complex but standard unix utility that compiles
what is needed in the way it is needed and in the order in which
it is needed (in Fortran you need to compile modules before programs
that use them, for instance). The configuration files for "make" are
either coming with the package or are generated by "configure".
If everything goes well, executables will appear in "bin/":
- Quick test (for "pw.x" executable only) to verify that things look good:
- Compile other packages. "make" with no argument yields a list
of targets, i.e., packages to be compiled. If you want to compile
Packages that are not contained in the base tarball will be download
from the net. Beware: this will work only if you have direct
access to the internet, and working "wget" or "curl" commands.
If not, you will need to download the required packages from
and to put them into "archive/". Then you can do "make" again.
Requirements for installation of a FAST executable
Most of the CPU time in a typical run is spent in:
If you want a fast executable, you MUST provide:
- Fast Fourier Transform
- matrix-matrix and matrix-vector multiplications (BLAS)
- solution of linear systems, diagonalizations (LAPACK)
Most vendors provide highly optimized BLAS and LAPACK replacements
and FFT libraries (different from FFTW)
- machine-optimized BLAS (VERY important) and LAPACK libraries (important)
- for some architectures (in particular IBM SP):
machine-optimized FFT library
Machine-optimized libraries: BLAS, LAPACK
The "configure" scripts can recognize and use the following
architecture-specific replacements for BLAS and LAPACK:
If none of these is available, you should try the ATLAS
(Automatically Tuned Linear Algebra Subroutines) library:
- ESSL for IBM machines
- MKL for Intel/AMD PCs
- ACML for AMD PCs
Machine-optimized libraries: FFT
Quantum ESPRESSO can use the following architecture-specific
mathematical libraries instead of FFTW:
You may want to check for the presence of preprocessing options
"-D" in the definition of DFLAGS in file "make.inc". For recent MKL
versions, it is sufficient to have "-D__FFTW3" in DFLAGS, to
have MKL properly linked, and nothing in FFTLIBS.
If none of the above is available, a precompiled FFTW v.3 library
or the built-in FFTW library contained in the distribution will be fine.
Their performances are quite good. Only ESSL on IBM machines beats
them by a large margin.
- ESSL for IBM machines
- MKL for Intel CPUs
- ACML for AMD CPUs
- ASL for NEC-SX machines
"configure" by default tries to compile support for ScaLAPACK
(check for "-D__SCALAPACK" in DFLAGS, file "make.inc"). For machines
with recent Intel MKL libraries, you may need to specify
depending upon whether you are linking Intel version of MPI or OpenMPI.
Most installation problems falls into one of the following categories:
- Fortran compiler not installed or not working
- buy a commercial compiler: Intel or PGI (the latter can be freely
downloaded, the former used to be free for personal usage but it is
- install or download the GNU "gfortran" compiler (recent versions
work quite well)
- Fortran compiler unable to compile Quantum ESPRESSO:
"internal compiler error" or some other strange errors occur.
- upgrade to the latest available compiler version,
or install the patches provided by the vendor (if any)
- install and try a different compiler
- try to figure out what to do: sometimes lowering
the optimization level of a specific routine, or splitting
a routine into pieces,
or simply moving around some lines, will do the job
- "configure" unable to locate some external libraries
you know are there.
- bug your system manager until he/she sets up properly
the libraries, or puts them in a sane location
- manually provide the correct location of libraries (you will have
to use "configure" options, or to edit file "make.inc")
- Parallel Machines (especially PC clusters):
In all cases mentioned above, see also the documentation on:
- configure says that there is a mismatch between the serial and
parallel compiler. Possible solution:
1) use "./configure F90=..."
of "MPIF90=..." to force the choice of the correct compiler
2) modify your $PATH so that "configure" finds the good combination
of serial and parallel compilers
- mpif90 doesn't work. Solution:
1) bug your system manager until he/she sets up properly the script
- you manage to compile but the executable yields strange
errors in parallel execution. Solution:
bug your system manager until he/she install a working combination
of libraries and of compiler
When everything else fails...
- ...read the manual and the documentation in directory Doc/
- search the users' mailing list (follow the link in the "Contacts" section
- post to the users' mailing list (subscribe by following
the link in the Contacts section of