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