1#############################
2Building from source on Linux
3#############################
4
5====================
6Generic instructions
7====================
8
9To build NumPy/SciPy from source, get the `source package
10<https://github.com/scipy/scipy>`__, unpack it, and:
11
12::
13
14   python setup.py install --user   # installs to your home directory
15
16or
17
18::
19
20   python setup.py build
21   python setup.py install --prefix=$HOME/local
22
23Before building, you will also need to install packages that NumPy and
24SciPy depend on
25
26* BLAS and LAPACK libraries (optional but strongly recommended for
27  NumPy, required for SciPy): typically `ATLAS
28  <http://math-atlas.sourceforge.net/>`__ + `OpenBLAS
29  <https://github.com/xianyi/OpenBLAS/>`__, or `MKL
30  <https://software.intel.com/en-us/intel-mkl>`__.
31
32* C and Fortran compilers (typically ``gcc`` and ``gfortran``).
33
34* Python header files (typically a package named ``python3-dev`` or ``python3-devel``)
35
36Typically, you will want to install all of the above from packages
37supplied by your Linux distribution, as building them yourself is
38complicated. If you need to use specific BLAS/LAPACK libraries, you
39can do
40
41::
42
43   export BLAS=/path/to/libblas.so
44   export LAPACK=/path/to/liblapack.so
45   export ATLAS=/path/to/libatlas.so
46   python setup.py ............
47
48* The `Cython <https://cython.org/>`__ and `Pythran <https://pythran.readthedocs.io>`__
49  ahead-of-time compilers are also necessary, as is ``pybind11``. It is
50  recommended to install these packages with ``pip`` or ``conda``, because it
51  is possible (even likely) that you need newer versions of these packages than
52  the ones that are available in your Linux distribution.
53
54
55Below, you will find additional installation instructions and advice
56for many major Linux distributions.
57
58
59=====================
60Specific instructions
61=====================
62
63.. contents::
64   :local:
65
66
67Debian / Ubuntu
68===============
69
70To build from source, the following packages are needed::
71
72   sudo apt-get install gcc gfortran python3-dev libopenblas-dev liblapack-dev
73
74To customize which BLAS is used, you can set up a `site.cfg` file. See
75the `site.cfg.example` file in the numpy source for the options you
76can set.
77
78Note that Debian and Ubuntu package optimized BLAS libraries in an
79exchangeable way. You can install libraries, such as ATLAS or OpenBLAS
80and change the default one used via the alternatives mechanism:
81
82::
83
84    $ sudo apt-get install libopenblas-base libatlas3-base
85    $ update-alternatives --list libblas.so.3
86    /usr/lib/atlas-base/atlas/libblas.so.3
87    /usr/lib/libblas/libblas.so.3
88    /usr/lib/openblas-base/libopenblas.so.0
89
90    $ sudo update-alternatives --set libblas.so.3 /usr/lib/openblas-base/libopenblas.so.0
91
92See /usr/share/doc/libatlas3-base/README.Debian for instructions on
93how to build optimized ATLAS packages for your specific CPU. The
94packaged OpenBLAS chooses the optimal code at runtime so it does not
95need recompiling unless the packaged version does not yet support the
96used CPU.
97
98You can also use a library you built yourself by preloading it. This does not
99require administrator rights.
100
101::
102
103    LD_PRELOAD=/path/to/libatlas.so.3 ./my-application
104
105
106Fedora 26
107=========
108
109To install scipy build requirements, you can do::
110
111    sudo dnf install gcc-gfortran python3-devel openblas-devel lapack-devel
112
113
114Intel C compiler and MKL
115========================
116
117Intel MKL 11.0 (updated Dec 2012)
118---------------------------------
119
120Add the following lines to site.cfg in your top level NumPy directory
121to use Intel® MKL for Intel® 64 (or earlier known as em64t)
122architecture, considering the default installation path of Intel® MKL,
123which is bundled with Intel® Composer XE SP1 version on Linux:
124
125::
126
127   [mkl]
128   library_dirs = /opt/intel/composer_xe_2013/mkl/lib/intel64
129   include_dirs = /opt/intel/composer_xe_2013/mkl/include
130   mkl_libs = mkl_intel_lp64,mkl_intel_thread,mkl_core
131
132If you are building NumPy for 32 bit, please add as the following
133
134::
135
136   [mkl]
137   library_dirs = /opt/intel/composer_xe_2013/mkl/lib/ia32
138   include_dirs = /opt/intel/composer_xe_2013/mkl/include
139   mkl_libs = mkl_intel,mkl_intel_thread,mkl_core
140
141Instead of the layered linking approach for the Intel® MKL as shown
142above, you may also use the dynamic interface lib mkl_rt.lib. So, for
143both the ia32 and intel64 architecture, make the change as below
144
145::
146
147   mkl_libs = mkl_rt
148
149Modify cc_exe in numpy/numpy/distutils/intelccompiler.py to be
150something like:
151
152::
153
154   cc_exe = 'icc -O2 -g -openmp -avx'
155
156Here, we use default optimizations (-O2), OpenMP threading (-openmp),
157and Intel® AVX optimizations for Intel® Xeon E5 or E3 Series, which are
158based on Intel® SandyBridge Architecture (-avx). Run icc --help for
159more information on processor-specific options.
160
161Compile and install NumPy with the Intel compiler (on 64-bit platforms replace "intel" with "intelem"):
162
163::
164
165   python setup.py config --compiler=intel build_clib --compiler=intel build_ext --compiler=intel install
166
167Compile and install SciPy with the Intel compilers (on 64-bit
168platforms replace "intel" with "intelem"):
169
170::
171
172   python setup.py config --compiler=intel --fcompiler=intel build_clib --compiler=intel --fcompiler=intel build_ext --compiler=intel --fcompiler=intel install
173
174You'll have to set LD_LIBRARY_PATH to Intel® MKL libraries (exact
175values will depend on your architecture, compiler, and library
176versions) and OpenMP library for NumPy to work. If you build NumPy
177for Intel® 64 platforms:
178
179::
180
181   $export LD_LIBRARY_PATH=/opt/intel/composer_xe_2013/mkl/lib/intel64: /opt/intel/composer_xe_2013/compiler/lib/intel64:$LD_LIBRARY_PATH
182
183If you build NumPy for ia32 bit platforms:
184
185::
186
187   $export LD_LIBRARY_PATH=/opt/intel/composer_xe_2013/mkl/lib/ia32: /opt/intel/composer_xe_2013/compiler/lib/ia32:$LD_LIBRARY_PATH
188
189
190====================
191Fortran ABI mismatch
192====================
193
194Some linear algebra libraries are built with G77 ABI and others with
195GFortran ABI, and these two ABIs are incompatible. Therefore, if you
196build scipy with `gfortran` and link to a linear algebra library, like
197MKL, which is built with G77 ABI, then there'll be an exception or a
198segfault. SciPy fixes this by using the CBLAS API for the few
199functions in the BLAS API that suffers from this issue.
200
201Note that SciPy needs to know at build time, what needs to be done and
202the build system will automatically check whether linear algebra
203library is MKL and if so, use the CBLAS API instead of the BLAS API.
204If autodetection fails or if the user wants to override this
205autodetection mechanism, setting the environment variable
206`SCIPY_USE_G77_ABI_WRAPPER` to 0 or 1 to disable or enable using CBLAS
207API.
208