Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 201 lines (139 sloc) 6.772 kB
d409225 @cournape Start working on a INSTALL.txt document for building/installing numpy.
cournape authored
1 .. -*- rest -*-
2 .. vim:syntax=rest
3 .. NB! Keep this document a valid restructured document.
4
5 Building and installing NumPy
6 +++++++++++++++++++++++++++++
7
8 :Authors: Numpy Developers <numpy-discussion@scipy.org>
9 :Discussions to: numpy-discussion@scipy.org
10
12320f4 @rgommers DOC: update INSTALL.txt with info on binary installers and 32-bit Win…
rgommers authored
11 **IMPORTANT**: the below notes are about building Numpy, which for most users
12 is *not* the recommended way to install Numpy. Instead, use either a complete
13 scientific Python distribution or a binary installer - see
14 http://scipy.org/install.html.
15
16
d409225 @cournape Start working on a INSTALL.txt document for building/installing numpy.
cournape authored
17 .. Contents::
18
19 PREREQUISITES
20 =============
21
22 Building NumPy requires the following software installed:
23
5866d03 @charris MAINT: Update INSTALL.txt after dropping Python 2.4, 2.5.
charris authored
24 1) For Python 2, Python__ 2.6.x or newer.
25 For Python 3, Python__ 3.2.x or newer.
d409225 @cournape Start working on a INSTALL.txt document for building/installing numpy.
cournape authored
26
27 On Debian and derivative (Ubuntu): python python-dev
28
29 On Windows: the official python installer on Python__ is enough
30
31 Make sure that the Python package distutils is installed before
32 continuing. For example, in Debian GNU/Linux, distutils is included
33 in the python-dev package.
34
35 Python must also be compiled with the zlib module enabled.
36
71c7a39 @rgommers DOC: update "build and install" page in user guide.
rgommers authored
37 2) nose__ (optional) 1.0 or later
7097f5a @cournape Mention nose for requirements.
cournape authored
38
39 This is required for testing numpy, but not for using it.
40
41 Python__ http://www.python.org
5aa65d9 TYP: Fix typo.
zed authored
42 nose__ http://somethingaboutorange.com/mrl/projects/nose/
5c08ef9 @cournape Mention which packages to install for atlas on Ubuntu (Pre intrepid a…
cournape authored
43
461bf42 @juliantaylor DOC: update installation instructions
juliantaylor authored
44 Basic Installation
45 ==================
46
47 To install numpy run:
48
49 python setup.py build -j 4 install --prefix $HOME/.local
50
51 This will compile numpy on 4 CPUs and install it into the specified prefix.
52 To perform an inplace build that can be run from the source folder run:
53
54 python setup.py build_ext --inplace -j 4
55
56 The number of build jobs can also be specified via the environment variable
57 NPY_NUM_BUILD_JOBS.
58
5e62187 @cournape Add mention of g77 vs gfortran in INSTALL notes.
cournape authored
59 Fortran ABI mismatch
60 ====================
61
62 The two most popular open source fortran compilers are g77 and gfortran.
63 Unfortunately, they are not ABI compatible, which means that concretely you
7019591 @charris MAINT: Improve INSTALL.txt wording and wrap lines at 75 characters.
charris authored
64 should avoid mixing libraries built with one with another. In particular,
65 if your blas/lapack/atlas is built with g77, you *must* use g77 when
66 building numpy and scipy; on the contrary, if your atlas is built with
67 gfortran, you *must* build numpy/scipy with gfortran.
5e62187 @cournape Add mention of g77 vs gfortran in INSTALL notes.
cournape authored
68
69 Choosing the fortran compiler
70 -----------------------------
71
72 To build with g77:
73
74 python setup.py build --fcompiler=gnu
75
76 To build with gfortran:
77
78 python setup.py build --fcompiler=gnu95
79
80 How to check the ABI of blas/lapack/atlas
81 -----------------------------------------
82
7019591 @charris MAINT: Improve INSTALL.txt wording and wrap lines at 75 characters.
charris authored
83 One relatively simple and reliable way to check for the compiler used to
84 build a library is to use ldd on the library. If libg2c.so is a dependency,
85 this means that g77 has been used. If libgfortran.so is a dependency,
86 gfortran has been used. If both are dependencies, this means both have been
87 used, which is almost always a very bad idea.
5e62187 @cournape Add mention of g77 vs gfortran in INSTALL notes.
cournape authored
88
461bf42 @juliantaylor DOC: update installation instructions
juliantaylor authored
89 Building with optimized BLAS support
90 ====================================
5c08ef9 @cournape Mention which packages to install for atlas on Ubuntu (Pre intrepid a…
cournape authored
91
461bf42 @juliantaylor DOC: update installation instructions
juliantaylor authored
92 Ubuntu/Debian
93 -------------
5c08ef9 @cournape Mention which packages to install for atlas on Ubuntu (Pre intrepid a…
cournape authored
94
461bf42 @juliantaylor DOC: update installation instructions
juliantaylor authored
95 In order to build with optimized a BLAS providing development package must be installed.
96 Options are for example:
419cd5b @cournape Disable looking for 3gf libraries; it causes more problem than it sol…
cournape authored
97
461bf42 @juliantaylor DOC: update installation instructions
juliantaylor authored
98 - libblas-dev
99 reference BLAS not very optimized
100 - libatlas-base-dev
101 generic tuned ATLAS, it is recommended to tune it to the available hardware,
102 see /usr/share/doc/libatlas3-base/README.Debian for instructions
103 - libopenblas-base
104 fast and runtime detected so no tuning required but as of version 2.11 still
105 suffers from correctness issues on some CPUs, test your applications
106 thoughly.
5c08ef9 @cournape Mention which packages to install for atlas on Ubuntu (Pre intrepid a…
cournape authored
107
461bf42 @juliantaylor DOC: update installation instructions
juliantaylor authored
108 The actual implementation can be exchanged also after installation via the
109 alternatives mechanism:
5c08ef9 @cournape Mention which packages to install for atlas on Ubuntu (Pre intrepid a…
cournape authored
110
461bf42 @juliantaylor DOC: update installation instructions
juliantaylor authored
111 update-alternatives --config libblas.so.3
112 update-alternatives --config liblapack.so.3
5c08ef9 @cournape Mention which packages to install for atlas on Ubuntu (Pre intrepid a…
cournape authored
113
461bf42 @juliantaylor DOC: update installation instructions
juliantaylor authored
114 Or by preloading a specific BLAS library with
115 LD_PRELOAD=/usr/lib/atlas-base/atlas/libblas.so.3 python ...
5c08ef9 @cournape Mention which packages to install for atlas on Ubuntu (Pre intrepid a…
cournape authored
116
f169313 @cournape Add notes on Windows for AMD64.
cournape authored
117
12320f4 @rgommers DOC: update INSTALL.txt with info on binary installers and 32-bit Win…
rgommers authored
118 Windows 32 bits notes
119 =====================
120
121 The MinGW compilers used to build the official Numpy binary installers for
122 32-bit Python on Windows can be found in https://github.com/numpy/numpy-vendor.
123 That repo also contains pre-built ATLAS binarues. The command to build and
124 install Numpy is:
125
126 $ python setup.py config --compiler=mingw32 build --compiler=mingw32 install
127
128 Typically, one needs to use a site.cfg file that looks like:
129
130 [atlas]
131 library_dirs = C:\local\lib\atlas
132 include_dirs = C:\local\lib\atlas
133
f169313 @cournape Add notes on Windows for AMD64.
cournape authored
134 Windows 64 bits notes
135 =====================
136
7019591 @charris MAINT: Improve INSTALL.txt wording and wrap lines at 75 characters.
charris authored
137 Note: only AMD64 is supported (IA64 is not) - AMD64 is the version most
138 people want.
f169313 @cournape Add notes on Windows for AMD64.
cournape authored
139
140 Free compilers (mingw-w64)
141 --------------------------
142
143 http://mingw-w64.sourceforge.net/
144
7019591 @charris MAINT: Improve INSTALL.txt wording and wrap lines at 75 characters.
charris authored
145 To use the free compilers (mingw-w64), you need to build your own
146 toolchain, as the mingw project only distribute cross-compilers
147 (cross-compilation is not supported by numpy). Since this toolchain is
148 still being worked on, serious compiler bugs can be expected. binutil 2.19
149 + gcc 4.3.3 + mingw-w64 runtime gives you a working C compiler (but the C++
150 is broken). gcc 4.4 will hopefully be able to run natively.
f169313 @cournape Add notes on Windows for AMD64.
cournape authored
151
7019591 @charris MAINT: Improve INSTALL.txt wording and wrap lines at 75 characters.
charris authored
152 This is the only tested way to get a numpy with a FULL blas/lapack (scipy
153 does not work because of C++).
f169313 @cournape Add notes on Windows for AMD64.
cournape authored
154
444b5ac @charris DOC: Document Carl Kleffner's MinGW-w64 toolchain in INSTALL.txt.
charris authored
155 Carl Kleffner's mingw-w64 toolchain
156 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
157
158 Carl Kleffner has been working on mingw-w64 / OpenBLAS support and has put
159 together toolchains for that option. The toolchains are available at
160 https://bitbucket.org/carlkl/mingw-w64-for-python/downloads. The site.cfg
161 should be configured like so:
162
12320f4 @rgommers DOC: update INSTALL.txt with info on binary installers and 32-bit Win…
rgommers authored
163 [openblas]
164 libraries = openblaspy
165 library_dirs = <openblaspath>/lib
166 include_dirs = <openblaspath>/include
444b5ac @charris DOC: Document Carl Kleffner's MinGW-w64 toolchain in INSTALL.txt.
charris authored
167
168 The libopenblaspy.dll from <openblaspath>/bin must be copied to numpy/core
169 before the build. For this mingw-w64 toolchain manual creation of the python
170 import libs is necessary, i.e.:
171
12320f4 @rgommers DOC: update INSTALL.txt with info on binary installers and 32-bit Win…
rgommers authored
172 gendef python2.7.dll
173 dlltool -D python27.dll -d python27.def -l libpython27.dll.a
174 move libpython27.dll.a libs\libpython27.dll.a
444b5ac @charris DOC: Document Carl Kleffner's MinGW-w64 toolchain in INSTALL.txt.
charris authored
175
176 For python-2.6 up to python 3.2 use
177 https://bitbucket.org/carlkl/mingw-w64-for-python/downloads/mingwpy_win32_vc90.tar.xz
178 or
179 https://bitbucket.org/carlkl/mingw-w64-for-python/downloads/mingwpy_amd64_vc90.tar.xz
180
181 For python-3.3 and python-3.4 use
182 https://bitbucket.org/carlkl/mingw-w64-for-python/downloads/mingwpy_win32_vc100.tar.xz
183 or
184 https://bitbucket.org/carlkl/mingw-w64-for-python/downloads/mingwpy_amd64_vc100.tar.xz
185
186
f169313 @cournape Add notes on Windows for AMD64.
cournape authored
187 MS compilers
188 ------------
189
7019591 @charris MAINT: Improve INSTALL.txt wording and wrap lines at 75 characters.
charris authored
190 If you are familiar with MS tools, that's obviously the easiest path, and
191 the compilers are hopefully more mature (although in my experience, they
192 are quite fragile, and often segfault on invalid C code). The main drawback
12320f4 @rgommers DOC: update INSTALL.txt with info on binary installers and 32-bit Win…
rgommers authored
193 is that mingw-w64 gfortran + MSVC does not work at all (it is unclear
194 whether it ever will). MSVC + ifort + MKL does work.
f169313 @cournape Add notes on Windows for AMD64.
cournape authored
195
196 For python 2.6, you need VS 2008. The freely available version does not
197 contains 64 bits compilers (you also need the PSDK, v6.1).
198
7019591 @charris MAINT: Improve INSTALL.txt wording and wrap lines at 75 characters.
charris authored
199 It is crucial to use the right MS compiler version. For python 2.6, you
200 must use version 15. You can check the compiler version with cl.exe /?.
Something went wrong with that request. Please try again.