Not a coder? Not a problem! NumPy is multi-faceted, and we can use a lot of help.
These are all activities we’d like to get help with (they’re all important, so
we list them in alphabetical order):
Code maintenance and development
Developing educational content & narrative documentation
Website design and development
Writing technical documentation
The rest of this document discusses working on the NumPy code base and documentation.
We’re in the process of updating our descriptions of other activities and roles.
If you are interested in these other activities, please contact us!
You can do this via
the numpy-discussion mailing list,
or on GitHub (open an issue or comment on a
relevant issue). These are our preferred communication channels (open source is open
by nature!), however if you prefer to discuss in private first, please reach out to
our community coordinators at firstname.lastname@example.org or numpy-team.slack.com
(send an email to email@example.com for an invite the first time).
Here’s the short summary, complete TOC links are below:
If you are a first-time contributor:
Go to https://github.com/numpy/numpy and click the
“fork” button to create your own copy of the project.
Clone the project to your local computer:
git clone https://github.com/your-username/numpy.git
Change the directory:
Add the upstream repository:
git remote add upstream https://github.com/numpy/numpy.git
Now, git remote -v will show two remote repositories named:
upstream, which refers to the numpy repository
origin, which refers to your personal fork
Develop your contribution:
Pull the latest changes from upstream:
git checkout master
git pull upstream master
Create a branch for the feature you want to work on. Since the
branch name will appear in the merge message, use a sensible name
such as ‘linspace-speedups’:
git checkout -b linspace-speedups
Commit locally as you progress (git add and git commit)
Use a properly formatted commit message,
write tests that fail before your change and pass afterward, run all the
tests locally. Be sure to document any
changed behavior in docstrings, keeping to the NumPy docstring
To submit your contribution:
Push your changes back to your fork on GitHub:
git push origin linspace-speedups
Enter your GitHub username and password (repeat contributors or advanced
users can remove this step by connecting to GitHub with
Go to GitHub. The new branch will show up with a green Pull Request
button. Make sure the title and message are clear, concise, and self-
explanatory. Then click the button to submit it.
If your commit introduces a new feature or changes functionality, post on
the mailing list to explain your changes. For bug fixes, documentation
updates, etc., this is generally not necessary, though if you do not get
any reaction, do feel free to ask for review.
Reviewers (the other developers and interested community members) will
write inline and/or general comments on your Pull Request (PR) to help
you improve its implementation, documentation and style. Every single
developer working on the project has their code reviewed, and we’ve come
to see it as friendly conversation from which we all learn and the
overall code quality benefits. Therefore, please don’t let the review
discourage you from contributing: its only aim is to improve the quality
of project, not to criticize (we are, after all, very grateful for the
time you’re donating!). See our Reviewer Guidelines for more information.
To update your PR, make your changes on your local repository, commit,
run tests, and only if they succeed push to your fork. As soon as
those changes are pushed up (to the same branch as before) the PR will
update automatically. If you have no idea how to fix the test failures,
you may push your changes anyway and ask for help in a PR comment.
Various continuous integration (CI) services are triggered after each PR
update to build the code, run unit tests, measure code coverage and check
coding style of your branch. The CI tests must pass before your PR can be
merged. If CI fails, you can find out why by clicking on the “failed”
icon (red cross) and inspecting the build and test log. To avoid overuse
and waste of this resource,
test your work locally before
A PR must be approved by at least one core team member before merging.
Approval means the core team member has carefully reviewed the changes,
and the PR is ready for merging.
Beyond changes to a functions docstring and possible description in the
general documentation, if your change introduces any user-facing
modifications they may need to be mentioned in the release notes.
To add your change to the release notes, you need to create a short file
with a summary and place it in doc/release/upcoming_changes.
The file doc/release/upcoming_changes/README.rst details the format and
If your change introduces a deprecation, make sure to discuss this first on
GitHub or the mailing list first. If agreement on the deprecation is
reached, follow NEP 23 deprecation policy to add the deprecation.
Cross referencing issues
If the PR relates to any issues, you can add the text xref gh-xxxx where
xxxx is the number of the issue to github comments. Likewise, if the PR
solves an issue, replace the xref with closes, fixes or any of
the other flavors github accepts.
In the source code, be sure to preface any issue or PR reference with
For a more detailed discussion, read on and follow the links at the bottom of
If GitHub indicates that the branch of your Pull Request can no longer
be merged automatically, you have to incorporate changes that have been made
since you started into your branch. Our recommended way to do this is to
rebase on master.
All code should have tests (see test coverage below for more details).
All code should be documented.
No changes are ever committed without review and approval by a core
team member. Please ask politely on the PR or on the mailing list if you
get no response to your pull request within a week.
Set up your editor to follow PEP 8 (remove trailing white space, no tabs, etc.). Check code with
pyflakes / flake8.
Use numpy data types instead of strings (np.uint8 instead of
Use the following import conventions:
import numpy as np
For C code, see NEP 45.
Pull requests (PRs) that modify code should either have new tests, or modify existing
tests to fail before the PR and pass afterwards. You should run the tests before pushing a PR.
Running NumPy’s test suite locally requires some additional packages, such as
pytest and hypothesis. The additional testing dependencies are listed
in test_requirements.txt in the top-level directory, and can conveniently
be installed with:
pip install -r test_requirements.txt
Tests for a module should ideally cover all code in that module,
i.e., statement coverage should be at 100%.
To measure the test coverage, install
and then run:
$ python runtests.py --coverage
This will create a report in build/coverage, which can be viewed with:
$ firefox build/coverage/index.html
To build docs, run make from the doc directory. make help lists
all targets. For example, to build the HTML documentation, you can run:
Then, all the HTML files will be generated in doc/build/html/.
Since the documentation is based on docstrings, the appropriate version of
numpy must be installed in the host python used to run sphinx.
Sphinx is needed to build
the documentation. Matplotlib, SciPy, and IPython are also required.
These additional dependencies for building the documentation are listed in
doc_requirements.txt and can be conveniently installed with:
pip install -r doc_requirements.txt
The numpy documentation also depends on the
numpydoc sphinx extension
as well as an external sphinx theme.
These extensions are included as git submodules and must be initialized
before building the docs.
From the doc/ directory:
git submodule update --init
The documentation includes mathematical formulae with LaTeX formatting.
A working LaTeX document production system
(e.g. texlive) is required for the
proper rendering of the LaTeX math in the documentation.
“citation not found: R###” There is probably an underscore after a
reference in the first line of a docstring (e.g. _). Use this
method to find the source file: $ cd doc/build; grep -rin R####
“Duplicate citation R###, other instance in…”” There is probably a
 without a  in one of the docstrings
The rest of the story
NumPy-specific workflow is in numpy-development-workflow.