You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Brigitta Sipőcz 87be1e426a
CI: Add weekly testing to CI via cron (#147)
3 weeks ago
.circleci Rm atari-py build deps from CI. 2 months ago
.github/workflows CI: Add weekly testing to CI via cron (#147) 3 weeks ago
content Update imageio.imread to v3.imread in x-ray img processing tutorial (#143) 1 month ago
site DOC: Add dollarmath to myst parser extension list (#135) 3 months ago
.gitignore Add generated files to .gitignore. 5 months ago
LICENSE.txt Initial commit - LICENSE, README, gitignore 3 years ago Add tutorial on timeseries analysis of air polution (#111) 8 months ago
environment.yml Add imageio to environment.yml 2 months ago
requirements.txt Also rm unused pooch dep. 2 months ago

NumPy tutorials

For the rendered tutorials, see

The goal of this repository is to provide high-quality resources by the NumPy project, both for self-learning and for teaching classes with. If you're interested in adding your own content, check the Contributing section. This set of tutorials and educational materials is not a part of the NumPy source tree.

To download a local copy of the .ipynb files, you can either clone this repository or navigate to any of the documents listed below and download it individually.


  1. Learn to write a NumPy tutorial: our style guide for writing tutorials.
  2. Tutorial: Linear algebra on n-dimensional arrays
  3. Tutorial: Determining Moore's Law with real data in NumPy
  4. Tutorial: Saving and sharing your NumPy arrays
  5. Tutorial: NumPy deep learning on MNIST from scratch
  6. Tutorial: X-ray image processing
  7. Tutorial: NumPy deep reinforcement learning with Pong from pixels
  8. Tutorial: Masked Arrays
  9. Tutorial: Static Equilibrium
  10. Tutorial: Plotting Fractals
  11. Tutorial: NumPy natural language processing from scratch with a focus on ethics
  12. Tutorial: Analysing the impact of the lockdown on air quality in Delhi, India


We very much welcome contributions! If you have an idea or proposal for a new tutorial, please open an issue with an outline.

Don’t worry if English is not your first language, or if you can only come up with a rough draft. Open source is a community effort. Do your best – we’ll help fix issues.

Images and real-life data make text more engaging and powerful, but be sure what you use is appropriately licensed and available. Here again, even a rough idea for artwork can be polished by others.

The NumPy tutorials are a curated collection of MyST-NB notebooks. These notebooks are used to produce static websites and can be opened as notebooks in Jupyter using Jupytext.

Note: You should use CommonMark markdown cells. Jupyter only renders CommonMark.

Why Jupyter Notebooks?

The choice of Jupyter Notebook in this repo instead of the usual format (reStructuredText, through Sphinx) used in the main NumPy documentation has two reasons:

  • Jupyter notebooks are a common format for communicating scientific information.
  • Jupyter notebooks can be launched in Binder, so that users can interact with tutorials
  • rST may present a barrier for some people who might otherwise be very interested in contributing tutorial material.


You may notice our content is in markdown format (.md files). We review and host notebooks in the MyST-NB format. We accept both Jupyter notebooks (.ipynb) and MyST-NB notebooks (.md). If you want to sync your .ipynb to your .md file follow the pairing tutorial.

Adding your own tutorials

If you have your own tutorial in the form of a Jupyter notebook (a .ipynb file) and you'd like to add it to the repository, follow the steps below.

Create an issue

Go to and create a new issue with your proposal. Give as much detail as you can about what kind of content you would like to write (tutorial, how-to) and what you plan to cover. We will try to respond as quickly as possible with comments, if applicable.

Check out our suggested template

You can use our Tutorial Style Guide to make your content consistent with our existing tutorials.

Upload your content

    Fork this repository (if you haven't before).
    In your own fork, create a new branch for your content.
    Add your notebook to the content/ directory.

    Update the environment.yml file with the dependencies for your tutorial (only if you add new dependencies).

    Update this to include your new entry.

    Update the attribution section (below) to credit the original tutorial author, if applicable.

    Create a pull request. Make sure the "Allow edits and access to secrets by maintainers" option is selected so we can properly review your submission.

    🎉 Wait for review!

For more information about GitHub and its workflow, you can see this document.

Building the Sphinx site locally

Building the tutorials website, which is published at, locally isn't necessary before making a contribution, but may be helpful:

conda env create -f environment.yml
conda activate numpy-tutorials
cd site
make html


While we don't have the capacity to translate and maintain translated versions of these tutorials, you are free to use and translate them to other languages.

The following links may be useful:

Note that regular documentation issues for NumPy can be found in the main NumPy repository (see the Documentation labels there).