Repository: pytorch/tutorials

Stars: 9115

CLAUDE.md Copy Chapter

Project Structure

This is the PyTorch Tutorials website (pytorch.org/tutorials), built with Sphinx and Sphinx Gallery.

- beginner_source/, intermediate_source/, advanced_source/, recipes_source/, unstable_source/ — tutorial source files (.py and .rst)
- index.rst, recipes_index.rst — card listings and toctrees for the website
- conf.py — Sphinx configuration (gallery dirs, extensions, theme)
- _static/ — images, CSS, and thumbnails
- requirements.txt — all Python dependencies (Sphinx, tutorial packages)
- .jenkins/ — CI build scripts, data download logic, post-processing
- Makefile — build entry points

Tutorials authored as .py files use Sphinx Gallery format: top-level docstrings become RST prose, code blocks become executable cells. These are executed during builds and converted to Jupyter notebooks and HTML. Tutorials authored as .rst are static and their code is not executed.

Build

- make html-noplot — builds HTML without executing tutorial code. Fast, no GPU needed. Use this for quick validation of RST/Sphinx structure.
- make docs — full build that downloads data, executes all .py tutorials, and produces the final site. Requires a GPU-powered machine with CUDA.
- GALLERY_PATTERN="my_tutorial.py" make html — build only a single tutorial by name (regex supported).

The CI build runs inside Docker across 15 GPU-powered shards via .jenkins/build.sh.

Linting

This repo uses lintrunner. Do not use spin, flake8, or other linters directly.

- lintrunner -m main — lint changes relative to the main branch
- lintrunner --all-files — lint all files in the repo

Lintrunner checks trailing whitespace, tabs, and newline issues only. It does not check Python formatting, RST syntax, or Sphinx directives.

Testing

There is no unit test suite. Validation is done by building tutorials:

- make html-noplot is the quick sanity check for RST and Sphinx errors.
- Full execution of .py tutorials runs in CI on GPU shards.
- To test a single tutorial: GALLERY_PATTERN="my_tutorial.py" make html

Tutorial File Format

- Interactive tutorials are .py files using Sphinx Gallery conventions. Filenames should end in _tutorial.py.
- Non-interactive tutorials are .rst files.
- Data dependencies must be added via .jenkins/download_data.py, not the Makefile. Follow the existing patterns in that file.
- New Python package dependencies go in requirements.txt.

Adding a New Tutorial

1. Place the file in the appropriate *_source/ directory based on difficulty level.
2. Add a customcarditem entry in index.rst (or recipes_index.rst for recipes).
3. Add the tutorial to the corresponding toctree in index.rst.
4. Add a square, high-resolution thumbnail image to _static/img/thumbnails/cropped/.

Coding Style Guidelines

Follow these rules for all code changes in this repository:

- Minimize comments; be concise; code should be self-explanatory.
- Match existing code style and architectural patterns.
- Tutorial prose should be written for a global audience with clear, easy to understand language. Avoid idioms.
- Use active voice in tutorial instructions.
- If uncertain, choose the simpler, more concise implementation.

README.md Copy Chapter

PyTorch Tutorials

All the tutorials are now presented as sphinx style documentation at:

https://pytorch.org/tutorials https://pytorch.org/tutorials')" title="Copy chapter prompt for LLMs"> Copy Chapter

Asking a question

If you have a question about a tutorial, post in https://dev-discuss.pytorch.org/ rather than creating an issue in this repo. Your question will be answered much faster on the dev-discuss forum.

Submitting an issue

You can submit the following types of issues:

* Feature request - request a new tutorial to be added. Please explain why this tutorial is needed and how it demonstrates PyTorch value.
* Bug report - report a failure or outdated information in an existing tutorial. When submitting a bug report, please run: python3 -m torch.utils.collect_env to get information about your environment and add the output to the bug report.

Contributing

We use sphinx-gallery's notebook styled examples to create the tutorials. Syntax is very simple. In essence, you write a slightly well formatted Python file and it shows up as an HTML page. In addition, a Jupyter notebook is autogenerated and available to run in Google Colab.

Here is how you can create a new tutorial (for a detailed description, see CONTRIBUTING.md):

NOTE: Before submitting a new tutorial, read PyTorch Tutorial Submission Policy.

1. Create a Python file. If you want it executed while inserted into documentation, save the file with the suffix tutorial so that the file name is your_tutorial.py.
2. Put it in one of the beginner_source, intermediate_source, advanced_source directory based on the level of difficulty. If it is a recipe, add it to recipes_source. For tutorials demonstrating unstable prototype features, add to the prototype_source.
3. For Tutorials (except if it is a prototype feature), include it in the toctree directive and create a customcarditem in index.rst.
4. For Tutorials (except if it is a prototype feature), create a thumbnail in the index.rst file using a command like .. customcarditem:: beginner/your_tutorial.html. For Recipes, create a thumbnail in the recipes_index.rst

If you are starting off with a Jupyter notebook, you can use this script to convert the notebook to Python file. After conversion and addition to the project, please make sure that section headings and other things are in logical order.

Building locally Copy Chapter

The tutorial build is very large and requires a GPU. If your machine does not have a GPU device, you can preview your HTML build without actually downloading the data and running the tutorial code:

1. Install required dependencies by running: pip install -r requirements.txt.

Typically, you would run either in conda or virtualenv. If you want to use virtualenv, in the root of the repo, run: virtualenv venv, then source venv/bin/activate.

- If you have a GPU-powered laptop, you can build using make docs. This will download the data, execute the tutorials and build the documentation to docs/ directory. This might take about 60-120 min for systems with GPUs. If you do not have a GPU installed on your system, then see next step.
- You can skip the computationally intensive graph generation by running make html-noplot to build basic html documentation to _build/html. This way, you can quickly preview your tutorial.

Building a single tutorial Copy Chapter

You can build a single tutorial by using the GALLERY_PATTERN environment variable. For example to run only neural_style_transfer_tutorial.py, run:

GALLERY_PATTERN="neural_style_transfer_tutorial.py" make html

GALLERY_PATTERN="neural_style_transfer_tutorial.py" sphinx-build . _build

The GALLERY_PATTERN variable respects regular expressions.

Spell Check Copy Chapter

pyspelling          # full check (~3 mins)
pyspelling -n python  # Python files only
pyspelling -n reST    # reST files (only beginner/ dir currently included)

About contributing to PyTorch Documentation and Tutorials Copy Chapter

License Copy Chapter

PyTorch Tutorials is BSD licensed, as found in the LICENSE file.