Installing NumPy
The only prerequisite for installing NumPy is Python itself. If you don’t have Python yet and want the simplest way to get started, we recommend you use the Anaconda Distribution — it includes Python, NumPy, and many other commonly used packages for scientific computing and data science.
NumPy can be installed with conda , with pip , with a package manager on macOS and Linux, or from source. For more detailed instructions, consult our Python and NumPy installation guide below.
CONDA
If you use conda , you can install NumPy from the defaults or conda-forge channels:
PIP
If you use pip , you can install NumPy with:
Also when using pip, it’s good practice to use a virtual environment — see Reproducible Installs below for why, and this guide for details on using virtual environments.
Python and NumPy installation guide
Installing and managing packages in Python is complicated, there are a number of alternative solutions for most tasks. This guide tries to give the reader a sense of the best (or most popular) solutions, and give clear recommendations. It focuses on users of Python, NumPy, and the PyData (or numerical computing) stack on common operating systems and hardware.
Recommendations
We’ll start with recommendations based on the user’s experience level and operating system of interest. If you’re in between “beginning” and “advanced”, please go with “beginning” if you want to keep things simple, and with “advanced” if you want to work according to best practices that go a longer way in the future.
Beginning users
On all of Windows, macOS, and Linux:
- Install Anaconda (it installs all packages you need and all other tools mentioned below).
- For writing and executing code, use notebooks in JupyterLab for exploratory and interactive computing, and Spyder or Visual Studio Code for writing scripts and packages.
- Use Anaconda Navigator to manage your packages and start JupyterLab, Spyder, or Visual Studio Code.
Advanced users
Conda
- Install Miniforge.
- Keep the base conda environment minimal, and use one or more conda environments to install the package you need for the task or project you’re working on.
Alternative if you prefer pip/PyPI
For users who know, from personal preference or reading about the main differences between conda and pip below, they prefer a pip/PyPI-based solution, we recommend:
- Install Python from python.org, Homebrew, or your Linux package manager.
- Use Poetry as the most well-maintained tool that provides a dependency resolver and environment management capabilities in a similar fashion as conda does.
Python package management
Managing packages is a challenging problem, and, as a result, there are lots of tools. For web and general purpose Python development there’s a whole host of tools complementary with pip. For high-performance computing (HPC), Spack is worth considering. For most NumPy users though, conda and pip are the two most popular tools.
Pip & conda
The two main tools that install Python packages are pip and conda . Their functionality partially overlaps (e.g. both can install numpy ), however, they can also work together. We’ll discuss the major differences between pip and conda here — this is important to understand if you want to manage packages effectively.
The first difference is that conda is cross-language and it can install Python, while pip is installed for a particular Python on your system and installs other packages to that same Python install only. This also means conda can install non-Python libraries and tools you may need (e.g. compilers, CUDA, HDF5), while pip can’t.
The second difference is that pip installs from the Python Packaging Index (PyPI), while conda installs from its own channels (typically “defaults” or “conda-forge”). PyPI is the largest collection of packages by far, however, all popular packages are available for conda as well.
The third difference is that conda is an integrated solution for managing packages, dependencies and environments, while with pip you may need another tool (there are many!) for dealing with environments or complex dependencies.
Reproducible installs
As libraries get updated, results from running your code can change, or your code can break completely. It’s important to be able to reconstruct the set of packages and versions you’re using. Best practice is to:
- use a different environment per project you’re working on,
- record package names and versions using your package installer; each has its own metadata format for this:
- Conda: conda environments and environment.yml
- Pip: virtual environments and requirements.txt
- Poetry: virtual environments and pyproject.toml
NumPy packages & accelerated linear algebra libraries
NumPy doesn’t depend on any other Python packages, however, it does depend on an accelerated linear algebra library — typically Intel MKL or OpenBLAS. Users don’t have to worry about installing those (they’re automatically included in all NumPy install methods). Power users may still want to know the details, because the used BLAS can affect performance, behavior and size on disk:
The NumPy wheels on PyPI, which is what pip installs, are built with OpenBLAS. The OpenBLAS libraries are included in the wheel. This makes the wheel larger, and if a user installs (for example) SciPy as well, they will now have two copies of OpenBLAS on disk.
In the conda defaults channel, NumPy is built against Intel MKL. MKL is a separate package that will be installed in the users’ environment when they install NumPy.
In the conda-forge channel, NumPy is built against a dummy “BLAS” package. When a user installs NumPy from conda-forge, that BLAS package then gets installed together with the actual library — this defaults to OpenBLAS, but it can also be MKL (from the defaults channel), or even BLIS or reference BLAS.
The MKL package is a lot larger than OpenBLAS, it’s about 700 MB on disk while OpenBLAS is about 30 MB.
MKL is typically a little faster and more robust than OpenBLAS.
Besides install sizes, performance and robustness, there are two more things to consider:
- Intel MKL is not open source. For normal use this is not a problem, but if a user needs to redistribute an application built with NumPy, this could be an issue.
- Both MKL and OpenBLAS will use multi-threading for function calls like np.dot , with the number of threads being determined by both a build-time option and an environment variable. Often all CPU cores will be used. This is sometimes unexpected for users; NumPy itself doesn’t auto-parallelize any function calls. It typically yields better performance, but can also be harmful — for example when using another level of parallelization with Dask, scikit-learn or multiprocessing.
Troubleshooting
If your installation fails with the message below, see Troubleshooting ImportError.
Name already in use
numpy.org / content / en / install.md
- Go to file T
- Go to line L
- Copy path
- Copy permalink
- Open with Desktop
- View raw
- Copy raw contents Copy raw contents
Copy raw contents
Copy raw contents
The only prerequisite for installing NumPy is Python itself. If you don’t have Python yet and want the simplest way to get started, we recommend you use the Anaconda Distribution — it includes Python, NumPy, and many other commonly used packages for scientific computing and data science.
NumPy can be installed with conda , with pip , with a package manager on macOS and Linux, or from source. For more detailed instructions, consult our Python and NumPy installation guide below.
CONDA
If you use conda , you can install NumPy from the defaults or conda-forge channels:
PIP
If you use pip , you can install NumPy with:
Also when using pip, it’s good practice to use a virtual environment — see Reproducible Installs below for why, and this guide for details on using virtual environments.
Python and NumPy installation guide
Installing and managing packages in Python is complicated, there are a number of alternative solutions for most tasks. This guide tries to give the reader a sense of the best (or most popular) solutions, and give clear recommendations. It focuses on users of Python, NumPy, and the PyData (or numerical computing) stack on common operating systems and hardware.
We’ll start with recommendations based on the user’s experience level and operating system of interest. If you’re in between «beginning» and «advanced», please go with «beginning» if you want to keep things simple, and with «advanced» if you want to work according to best practices that go a longer way in the future.
On all of Windows, macOS, and Linux:
- Install Anaconda (it installs all packages you need and all other tools mentioned below).
- For writing and executing code, use notebooks in JupyterLab for exploratory and interactive computing, and Spyder or Visual Studio Code for writing scripts and packages.
- Use Anaconda Navigator to manage your packages and start JupyterLab, Spyder, or Visual Studio Code.
- Install Miniforge.
- Keep the base conda environment minimal, and use one or more conda environments to install the package you need for the task or project you’re working on.
Alternative if you prefer pip/PyPI
For users who know, from personal preference or reading about the main differences between conda and pip below, they prefer a pip/PyPI-based solution, we recommend:
- Install Python from python.org, Homebrew, or your Linux package manager.
- Use Poetry as the most well-maintained tool that provides a dependency resolver and environment management capabilities in a similar fashion as conda does.
Python package management
Managing packages is a challenging problem, and, as a result, there are lots of tools. For web and general purpose Python development there’s a whole host of tools complementary with pip. For high-performance computing (HPC), Spack is worth considering. For most NumPy users though, conda and pip are the two most popular tools.
The two main tools that install Python packages are pip and conda . Their functionality partially overlaps (e.g. both can install numpy ), however, they can also work together. We’ll discuss the major differences between pip and conda here — this is important to understand if you want to manage packages effectively.
The first difference is that conda is cross-language and it can install Python, while pip is installed for a particular Python on your system and installs other packages to that same Python install only. This also means conda can install non-Python libraries and tools you may need (e.g. compilers, CUDA, HDF5), while pip can’t.
The second difference is that pip installs from the Python Packaging Index (PyPI), while conda installs from its own channels (typically «defaults» or «conda-forge»). PyPI is the largest collection of packages by far, however, all popular packages are available for conda as well.
The third difference is that conda is an integrated solution for managing packages, dependencies and environments, while with pip you may need another tool (there are many!) for dealing with environments or complex dependencies.
As libraries get updated, results from running your code can change, or your code can break completely. It’s important to be able to reconstruct the set of packages and versions you’re using. Best practice is to:
- use a different environment per project you’re working on,
- record package names and versions using your package installer; each has its own metadata format for this:
- Conda: conda environments and environment.yml
- Pip: virtual environments and requirements.txt
- Poetry: virtual environments and pyproject.toml
NumPy packages & accelerated linear algebra libraries
NumPy doesn’t depend on any other Python packages, however, it does depend on an accelerated linear algebra library — typically Intel MKL or OpenBLAS. Users don’t have to worry about installing those (they’re automatically included in all NumPy install methods). Power users may still want to know the details, because the used BLAS can affect performance, behavior and size on disk:
The NumPy wheels on PyPI, which is what pip installs, are built with OpenBLAS. The OpenBLAS libraries are included in the wheel. This makes the wheel larger, and if a user installs (for example) SciPy as well, they will now have two copies of OpenBLAS on disk.
In the conda defaults channel, NumPy is built against Intel MKL. MKL is a separate package that will be installed in the users’ environment when they install NumPy.
In the conda-forge channel, NumPy is built against a dummy «BLAS» package. When a user installs NumPy from conda-forge, that BLAS package then gets installed together with the actual library — this defaults to OpenBLAS, but it can also be MKL (from the defaults channel), or even BLIS or reference BLAS.
The MKL package is a lot larger than OpenBLAS, it’s about 700 MB on disk while OpenBLAS is about 30 MB.
MKL is typically a little faster and more robust than OpenBLAS.
Besides install sizes, performance and robustness, there are two more things to consider:
- Intel MKL is not open source. For normal use this is not a problem, but if a user needs to redistribute an application built with NumPy, this could be an issue.
- Both MKL and OpenBLAS will use multi-threading for function calls like np.dot , with the number of threads being determined by both a build-time option and an environment variable. Often all CPU cores will be used. This is sometimes unexpected for users; NumPy itself doesn’t auto-parallelize any function calls. It typically yields better performance, but can also be harmful — for example when using another level of parallelization with Dask, scikit-learn or multiprocessing.
If your installation fails with the message below, see Troubleshooting ImportError.
Obtaining NumPy & SciPy¶
For each official release of NumPy and SciPy, we provide source code (tarball) as well as binary packages for several major platforms. Binary packages for other platforms may be available from your operating system vendor.
| Project | Available packages | Download location |
|---|---|---|
| NumPy | Official source code (all platforms) and binaries for Windows & Mac OS X | SourceForge site for NumPy |
| SciPy | Official source code (all platforms) and binaries for Windows & Mac OS X | SourceForge site for SciPy |
Build instructions are available for linux, windows and Mac OSX.
Bleeding Edge Repository Access¶
The most recent development versions of NumPy and SciPy are available through the official repositories hosted on Github.
To check out the latest NumPy sources:
or (if you’re behind a proxy blocking git ports)
To check out the latest SciPy sources:
Software Distributions that include NumPy/SciPy¶
A number of software distributions exist that bundle NumPy and SciPy along with a variety of other tools, including data file manipulation packages, visualization tools and more general software development tools. Such distributions can be an excellent way to get started with Python for scientific computing.
We present a list of the most prominent such distributions below. They vary in terms of platform/operating system support, license (free/commercial), packages included, and general focus (general/interactive scientific computing vs. mathematics/computer algebra vs. scientific software/GUI development). If you hope to transition to using Python as your every day scientific computing environment, these distributions are well worth investigating.
Enthought Python Distribution¶
The Enthought Python Distribution (EPD) is a “kitchen-sink-included” distribution of the Python programming language, including over 80 additional tools and libraries. The EPD bundle includes NumPy, SciPy, IPython, 2D and 3D visualization, database adapters, and a lot of other tools right out of the box.
It is currently available as a single-click installer for Windows XP (x86), Mac OS X (a universal binary for OS X 10.4 and above), RedHat 3, 4 and 5, as well as Solaris 10 (x86 and x86_64/amd64).
EPD is free for academic use. An annual subscription including installation support is available for individual and commercial use. You can download a 30-day free trial at the Enthought website.
Python(x,y)¶
Python(x,y) is a distribution of free/open source scientific and engineering software for Microsoft Windows XP/Vista (although there is an effort underway to develop an Ubuntu Linux version) based around Qt and Eclipse. It aims to provide an environment for interactive scientific computing as well as more development-oriented features such as integrated GUI design tools for scientific software development. More details as well as downloads are available on at the Python(x,y) website.
Sage is a monolithic distribution of a wide variety of open source mathematical software available in both source and binary forms for a number of operating systems, including Linux (x86/amd64), Mac OS X, Solaris, and Windows (through VMware Player). A bootable Sage LiveCD is also available.
Sage bundles recent versions of both NumPy and SciPy, along with its own Python interpreter. See the Sage Installation Guide for installation instructions.
SciPy Superpack (OS X)¶
The Superpack provides bleeding edge binaries of NumPy and SciPy from recent Subversion checkouts, maintained by Chris Fonnesbeck. It is available from MacInScience.org.
The Superpack requires Mac OS X 10.5 Leopard with either Apple’s preinstalled Python 2.5.1, ActivePython 2.5 or Python 2.5 from Python.org. Note that the Superpack’s version detection may fail with other Python distributions (e.g. Python installed by Fink and MacPorts) and it will refuse to install. If you are using Python provided by Fink or MacPorts it is recommended that you install NumPy/SciPy with the appropriate packages (see Third-Party/Vendor Package Managers below).
NOTE: NumPy is included in the Superpack. For best compatibility, it is recommended that you use the NumPy provided with the Superpack rather than a separately installed version.
Source Python Distribution¶
Source Python Distribution (SPD) is a Python distribution based on Sage, containing many optional (mainly scientific) packages that build from source. It contains only a small subset of Sage (an approximately 60 MB download compared with Sage’s several hundred megabytes). It bundles recent versions of NumPy and SciPy, and is compatible with Sage’s packages format so that you can selectively install other pieces of software included in Sage but not in SPD. See the SPD website for details.
Third-Party/Vendor Package Managers¶
Below is a partial list of third-party and operating system vendor package managers containing NumPy and SciPy packages.
These packages are not maintained by the NumPy and SciPy developers; this list is provided only as a convenience. These packages may not always provide the most up to date version of the software, and may be unmaintained.
IMPORTANT: If you experience problems with these packages (especially those related to installation/build errors), please report the problem to the package maintainer first, rather than to the NumPy/SciPy mailing lists.
numpy 1.24.3
NumPy is the fundamental package for scientific computing with Python.
- Website:https://www.numpy.org
- Documentation:https://numpy.org/doc
- Mailing list:https://mail.python.org/mailman/listinfo/numpy-discussion
- Source code:https://github.com/numpy/numpy
- Contributing:https://www.numpy.org/devdocs/dev/index.html
- Bug reports:https://github.com/numpy/numpy/issues
- Report a security vulnerability:https://tidelift.com/docs/security
- a powerful N-dimensional array object
- sophisticated (broadcasting) functions
- tools for integrating C/C++ and Fortran code
- useful linear algebra, Fourier transform, and random number capabilities
NumPy requires pytest and hypothesis . Tests can then be run after installation with:
Code of Conduct
NumPy is a community-driven open source project developed by a diverse group of contributors. The NumPy leadership has made a strong commitment to creating an open, inclusive, and positive community. Please read the NumPy Code of Conduct for guidance on how to interact with others in a way that makes our community thrive.
Call for Contributions
The NumPy project welcomes your expertise and enthusiasm!
Small improvements or fixes are always appreciated. If you are considering larger contributions to the source code, please contact us through the mailing list first.
Writing code isn’t the only way to contribute to NumPy. You can also:
- review pull requests
- help us stay on top of new and old issues
- develop tutorials, presentations, and other educational materials
- maintain and improve our website
- develop graphic design for our brand assets and promotional materials
- translate website content
- help with outreach and onboard new contributors
- write grant proposals and help with other fundraising efforts
For more information about the ways you can contribute to NumPy, visit our website. If you’re unsure where to start or how your skills fit in, reach out! You can ask on the mailing list or here, on GitHub, by opening a new issue or leaving a comment on a relevant issue that is already open.
Our preferred channels of communication are all public, but if you’d like to speak to us in private first, contact our community coordinators at numpy-team@googlegroups.com or on Slack (write numpy-team@googlegroups.com for an invitation).
We also have a biweekly community call, details of which are announced on the mailing list. You are very welcome to join.
If you are new to contributing to open source, this guide helps explain why, what, and how to successfully get involved.