Examples and Notebooks

Purpose and Scope

This page helps you choose the right runnable learning artifact when working with Transformers: documentation notebooks, task-oriented example scripts, and localized notebook indexes. In this repository, the notebook surface is part of the documentation site rather than a standalone Python package API. The English notebook page delegates to the shared notebooks README, while the Arabic documentation contains a translated notebook index with the same reader intent: gather official Hugging Face notebooks and make them easy to open in hosted environments. Sources: docs/source/en/notebooks.md, docs/source/ar/notebooks.md

Use this page when you want a practical path from reading a guide to executing code. Notebooks are best for exploratory learning because they pair prose, setup cells, and small runnable examples. Example scripts are better when you want a maintained training or evaluation recipe that can be adapted to a real dataset or production-like training run. The official docs framing is explicit that examples are examples: readers should expect to edit preprocessing, arguments, and dataset handling for their own use case rather than treating scripts as universal drop-in programs.

Relevant Source Files

docs/source/ar/notebooks.md — Arabic localized notebook catalog, including the translated title, introductory contribution guidance, documentation notebook table, and links to Colab and AWS StudioLab launch targets.
docs/source/en/notebooks.md — English documentation entry point for notebooks; it points the published English page at the shared notebooks README content.
docs/source/_config.py — English documentation build configuration that injects an installation code cell into generated notebooks and defines placeholder names that should avoid automatic formatting changes.
docs/source/ar/_config.py — Arabic documentation build configuration with the same notebook first-cell installation block and formatting placeholder protections.
docs/source/ar/_toctree.yml — Arabic documentation navigation tree that places the notebooks page under the broader guides section as “دفاتر الملاحظات مع الأمثلة”.

Notebook Catalog and Reader Workflow

The notebook catalog is organized for readers who want to open a working environment immediately. The Arabic page begins by explaining that it lists official notebooks provided by Hugging Face, and it also invites community-created notebook content through pull requests. That distinction matters: official notebooks are curated learning paths, while community notebooks can broaden coverage when contributors have useful workflows to share. The table shown in the localized page includes documentation notebooks such as the library quicktour, task summary, preprocessing, fine-tuning a pretrained model, tokenizer summary, and multilingual models. Sources: docs/source/ar/notebooks.md

The launch options in the notebook table show the expected workflow. A reader can start from a topic, choose a hosted runtime such as Colab or AWS StudioLab, and run cells without first cloning the full repository. That makes notebooks useful for the early stages of adoption: validating that the library imports, seeing the shape of inputs and outputs, and experimenting with small model calls. Once a workflow becomes larger or needs reproducible command-line execution, readers should graduate to task guides and example scripts rather than continuing to grow a notebook into an application.

The English documentation path is intentionally thin in the requested source evidence: it consists of an include-style pointer to the shared notebooks README. This means the published English notebook page is maintained through a shared source rather than duplicating the notebook catalog in that file. From a documentation-maintenance perspective, that pattern helps keep the English notebooks page aligned with the central notebook list. From a reader perspective, the important behavior is the same: the documentation site exposes a notebook index where official notebooks are grouped and linked. Sources: docs/source/en/notebooks.md

Generated Notebook Setup Cells

The documentation build configuration adds a standard first code cell for notebooks generated from docs content. The installation cell installs transformers, datasets, evaluate, and accelerate, and it includes a commented alternative for installing Transformers directly from the GitHub repository. This is a small but important part of the notebook experience: readers who open documentation-derived notebooks get the expected runtime dependencies before the tutorial-specific code begins. Sources: docs/source/_config.py, docs/source/ar/_config.py

# Transformers installation
! pip install transformers datasets evaluate accelerate
# To install from source instead of the last release, comment the command above and uncomment the following one.
# ! pip install git+https://github.com/huggingface/transformers.git

The same installation snippet appears in both the default and Arabic documentation configurations, which keeps localized notebook behavior consistent with the English documentation build. The config also defines placeholder substitutions such as FakeProcessorClass, FakeModelClass, and FakeObjectClass for patterns like {processor_class}, {model_class}, and {object_class}. Those placeholders are not reader-facing notebook APIs; they protect templated documentation examples from being reformatted incorrectly. When adding notebook-friendly docs, preserve this build-time concern so generated notebooks remain both executable and readable. Sources: docs/source/_config.py, docs/source/ar/_config.py

Examples, Scripts, and When to Use Each

Notebooks and scripts serve different points in the same learning-to-production journey. Start with a notebook when your goal is to understand a concept, follow an official tutorial, or test a task interactively. Move to an example script when your goal is repeatability: running from the command line, passing structured arguments, truncating samples for smoke tests, or adapting preprocessing for a dataset. The official training-script guidance emphasizes installing the current source version for the latest examples and checking script-specific requirements before running a recipe.

A practical sequence is to begin with the quicktour or task-summary notebook, then open the preprocessing or training notebook for the exact concept you need, and finally move to the maintained task guide or training script once the notebook flow is clear. This sequencing avoids two common problems: copying a notebook cell into a larger project without understanding the abstractions, and over-engineering an example script before validating the model, tokenizer, processor, or dataset shape. The notebook catalog exists to shorten the first feedback loop, not to replace the lower-level APIs.

The Arabic toctree shows where the notebooks page appears in the localized documentation hierarchy. It is placed in a broader guides area alongside pages for fast tokenizers, multilingual inference, model APIs, custom models, chat templates, Trainer, SageMaker, serialization, and community content. That placement signals that notebooks are not only a beginner quickstart feature; they are a cross-cutting companion to guides that readers may revisit when they want runnable versions of documentation concepts. Sources: docs/source/ar/_toctree.yml

Localization also affects discoverability. The Arabic notebook page translates the surrounding explanations and notebook titles while keeping the underlying notebook targets pointed at the maintained Hugging Face notebook assets. Contributors who update notebook documentation should therefore consider both the shared source used by the English page and localized pages that may carry translated tables or navigation labels. A notebook link update can be technically simple but reader-visible in multiple documentation surfaces, especially where localized toctrees expose the page under translated section names.

Task-Oriented Next Steps

If you are new to Transformers, open the quicktour notebook first, then use the task-summary notebook to identify the model family and pipeline shape for your problem. If your next step is training, use the preprocessing and fine-tuning notebooks to understand the data path before adapting an example script. If you are maintaining docs, check the notebook first-cell configuration so generated notebooks install the same baseline packages across locales. For broader runnable recipes, continue to the Training Scripts page and the task-specific guides that cover text, vision, audio, and multimodal workflows in more detail.

Ask a question...