GO — Healthy across all four use cases

• Last commit 8mo ago
• 38+ active contributors
• Distributed ownership (top contributor 18% of recent commits)
• BSD-3-Clause licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 8mo ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

pytorch/examples is a curated collection of runnable, production-quality example implementations across computer vision, NLP, reinforcement learning, and C++ binding use cases. It demonstrates PyTorch capabilities through isolated, few-dependency projects like MNIST classification, DCGAN, language modeling, distributed training, and neural style transfer—each with its own README and often minimal external dependencies. Flat, domain-organized monorepo: top-level directories by domain (mnist/, dcgan/, reinforcement_learning/, language_translation/, imagenet/, etc.) plus a separate cpp/ subtree with CMake-based C++ examples. Each example is standalone with its own README, source files, and optional requirements.txt. No shared src/ or lib/—examples are intentionally decoupled for independent learning.

Machine learning engineers, researchers, and PyTorch users learning how to implement specific architectures (CNNs, RNNs, Transformers, GANs) and training patterns (distributed data parallel, reinforcement learning, transfer learning). Also C++ developers using LibTorch (PyTorch's C++ API) for production inference.

Actively maintained with established CI/CD (GitHub workflows for Python, C++, distributed examples, and documentation builds). The repo structure and curated example list indicate organizational maturity, though it functions as a reference collection rather than a single versioned product. Examples span foundational (MNIST) to advanced (distributed RPC, FX transformations), suggesting broad coverage.

Standard open source risks apply.

Active maintenance indicated by GitHub workflows (doc-build.yml, main_python.yml, main_cpp.yml, main_distributed.yaml) and CODEOWNERS file. The repo tracks PyTorch releases and updates examples. Specific active areas: distributed training patterns (DDP and RPC in ./distributed/), modern architectures (Transformers in word_language_model/, language_translation/), and forward-forward learning (mnist_forward_forward/).

git clone https://github.com/pytorch/examples.git && cd examples && pip install torch torchvision. For a specific example (e.g., MNIST): cd mnist && pip install -r requirements.txt && python main.py. For C++ examples: cd cpp/mnist && mkdir build && cd build && cmake .. && make.

Daily commands: Varies by example. Python: typically python main.py [--args] after pip install -r requirements.txt. See mnist/main.py for simple template. Distributed: python -m torch.distributed.launch --nproc_per_node=N main.py. C++: cmake .. && make && ./executable. Check individual README.md files (e.g., ./dcgan/README.md, ./reinforcement_learning/README.md) for example-specific flags and data download instructions.

• README.md: Master index listing all ~20 examples with links—entry point for understanding what's available
• mnist/main.py: Canonical simple PyTorch training example: ConvNet on MNIST with clear train/test loops, good template for beginners
• dcgan/main.py: Demonstrates adversarial training pattern with two interacting models, key architectural pattern in deep learning
• reinforcement_learning/README.md: Bridges PyTorch to OpenAI gym and actor-critic algorithms, illustrates policy gradient training
• cpp/mnist/mnist.cpp: Parallel to mnist/main.py but in LibTorch C++ API, shows production inference patterns
• distributed/ddp/README.md: Teaches PyTorch Distributed Data Parallel setup, essential for multi-GPU/multi-node training
• word_language_model/main.py: Implements RNN and Transformer models for sequence tasks, demonstrates modern NLP architecture progression
• .github/workflows/main_python.yml: CI definition: shows which examples are tested and how, guards against API breakage

Start by selecting a domain directory (mnist/, dcgan/, reinforcement_learning/, etc.). Open its main.py or .cpp file to understand the model architecture. Modify: (1) model definition in the class, (2) training loop in the main/train function, (3) hyperparameters at the top of main(). For C++ changes, edit the .cpp file and CMakeLists.txt dependency list. Test by running the example end-to-end to ensure convergence/output quality.

(1) MNIST data auto-downloads on first run to ./data/—ensure disk space and internet. (2) C++ examples require LibTorch binary matching your OS/CUDA version; building from source is slow. (3) Some examples use deprecated torchtext APIs (e.g., snli/)—check torch version compatibility. (4) Distributed examples require NCCL or Gloo backend; Linux + CUDA assumed. (5) No centralized requirements.txt—each example pins dependencies independently, which can cause conflicts if run in same env.

• Generative Adversarial Networks (GANs) — dcgan/ exemplifies the adversarial training loop (generator vs discriminator) which is non-intuitive; understanding why both networks improve simultaneously is critical for generative modeling
• Distributed Data Parallel (DDP) — distributed/ddp/ teaches gradient synchronization across GPUs/nodes without code changes to model—essential for scaling training beyond single GPU
• Attention Mechanism & Transformers — word_language_model/ implements both RNN and Transformer variants; understanding the self-attention computational pattern is mandatory for modern NLP
• Policy Gradient & Actor-Critic — reinforcement_learning/ demonstrates gradient-based policy optimization; the critic network (value function) reduces variance, a key RL insight often misunderstood
• PyTorch JIT & TorchScript — fx/ examples use symbolic execution and module transformations; necessary to understand for production deployment and optimization beyond eager execution
• Forward-Forward Algorithm — mnist_forward_forward/ implements an alternative to backprop using local loss per layer; emerging alternative training paradigm worth studying for energy efficiency research
• LibTorch C++ API — cpp/ examples show how to load models trained in Python and run inference in C++ without Python runtime; critical for production deployments and mobile/embedded systems

• pytorch/tutorials — Deep-dive tutorials and conceptual guides paired with examples; where learners go after understanding the patterns shown here
• pytorch/pytorch — The PyTorch framework itself—these examples validate its public API and serve as user-facing reference implementations
• huggingface/transformers — Pre-trained model zoo and training recipes; natural next step for NLP examples (word_language_model/, language_translation/) in production
• pytorch/vision — Companion library providing pre-trained vision models (ResNet, VGG) and datasets used by imagenet/ and transfer_learning/ examples
• pytorch/text — Dataset loading and preprocessing utilities (torchtext) used by snli/ and word_language_model/ examples

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add CI workflow to validate C++ examples build successfully across platforms

The repo has a .github/workflows/main_cpp.yml workflow file but the file structure shows multiple C++ examples (mnist, dcgan, transfer-learning, distributed, etc.) with CMakeLists.txt files. There's no evidence these are being tested in CI. A robust C++ CI pipeline would catch build breaks early and ensure cross-platform compatibility (Linux, macOS, Windows). This is critical for C++ users who rely on these examples.

• [ ] Review existing .github/workflows/main_cpp.yml to understand current scope
• [ ] Add build steps for each C++ example in cpp/*/CMakeLists.txt
• [ ] Configure matrix testing for multiple CMake versions and compilers (gcc, clang, MSVC)
• [ ] Add dependency checks for OpenCV (referenced in cpp/tools/InstallingOpenCV.md)
• [ ] Test on at least Linux and macOS runners in GitHub Actions

Create requirements.txt validation and update workflow for all Python examples

The repo has scattered requirements.txt files (e.g., dcgan/requirements.txt, distributed/FSDP/requirements.txt) but no centralized CI validation. Without pinned versions and compatibility testing, contributors may introduce broken dependencies. A workflow that validates all requirements.txt files are parseable, checks for version conflicts, and runs basic import tests would prevent dependency-related issues.

• [ ] Audit all Python example directories for missing or outdated requirements.txt files
• [ ] Create a new GitHub Actions workflow .github/workflows/validate_requirements.yml
• [ ] Add a Python script to parse and validate all requirements.txt files exist and have proper syntax
• [ ] Add pip dependency conflict checking using pip check or pipdeptree
• [ ] Document minimum Python version support (likely 3.8+) and add to validation

Add missing README.md files and standardize example documentation structure

The repo lists available models in the main README (MNIST, Language Modeling, ImageNet, GANs) but the file structure shows some directories lack visible documentation. For instance, distributed/FSDP/ has a README but other examples may have incomplete docs. Standardizing all example READMEs with consistent sections (Overview, Requirements, Usage, Results) and ensuring every top-level example dir has one would improve discoverability and reduce contributor friction.

• [ ] Audit all top-level example directories (dcgan/, distributed/, cpp/*, etc.) for README presence
• [ ] Create a documentation template in .github/ or docs/ for example READMEs
• [ ] Write missing READMEs for examples that lack them, following the template
• [ ] Ensure each README includes: description, dependencies, setup instructions, and expected output
• [ ] Update main README.md to link to all example READMEs and maintain consistency

• Add type hints to mnist/main.py and other Python examples lacking them—improves clarity for learners and catches bugs. Affects: mnist/, dcgan/, time_sequence_prediction/.
• Create unified requirements.txt with pinned versions at repo root covering Python examples, and update CI to test against it—currently each example manages deps separately, causing maintenance burden.
• Write a quickstart script (e.g., scripts/run_example.sh) that handles data downloads, env setup, and execution for any example, reducing first-run friction documented in multiple READMEs.

The pytorch/examples repository demonstrates a moderate security posture. The primary concerns are related to unsafe handling of downloaded models and datasets (common in ML projects), potential deserialization vulnerabilities with LMDB, and lack of explicit vulnerability disclosure procedures. The codebase itself appears to be example-focused rather than production code, which mitigates some risks. However, since examples are often used as templates for production systems, incorporating security best practices and validation patterns would be beneficial. No critical vulnerabilities were identified, but the identified medium and low-severity issues should be addressed to improve the security guidance provided to users.

• Medium · Potential Unsafe Deserialization with LMDB — dependencies (lmdb package). The codebase includes 'lmdb' as a dependency, which is used for key-value storage. LMDB can be vulnerable to unsafe deserialization attacks if untrusted data is loaded without proper validation. This is particularly concerning in machine learning examples where datasets might be sourced from external or user-provided locations. Fix: Validate and sanitize all data loaded from LMDB databases. Ensure datasets come from trusted sources only. Consider implementing integrity checks (checksums/signatures) for downloaded datasets.
• Medium · Missing Security Policy and Vulnerability Disclosure — .github directory structure. While CONTRIBUTING.md exists, there is no explicit SECURITY.md file visible in the repository structure. This makes it difficult for security researchers to report vulnerabilities responsibly, potentially leading to public disclosure of security issues. Fix: Create a SECURITY.md file in the root directory with clear instructions for responsible vulnerability disclosure, including contact information and expected response times.
• Low · Potential Arbitrary Code Execution via Model Downloads — distributed/FSDP, cpp/tools (download_mnist.py), imagenet examples. PyTorch examples frequently involve downloading pre-trained models and datasets from the internet. Without cryptographic verification (checksums), there is a risk of man-in-the-middle attacks or compromised sources delivering malicious model files that could execute arbitrary code. Fix: Implement cryptographic verification (SHA256 checksums) for all downloaded models and datasets. Use HTTPS with certificate pinning where possible. Document the source and expected checksums for all downloaded artifacts.
• Low · Python Script Execution in Download Tools — cpp/tools/download_mnist.py, distributed/FSDP/download_dataset.sh. The file 'cpp/tools/download_mnist.py' and 'distributed/FSDP/download_dataset.sh' execute Python and shell scripts to download datasets. If these scripts are modified or if dependencies are compromised, they could execute arbitrary code. Fix: Pin specific versions of downloaded datasets and models. Verify integrity using checksums before execution. Review all download scripts for hardcoded URLs and ensure they use HTTPS only.
• Low · No Input Validation Pattern Documentation — Overall codebase structure. The examples codebase does not appear to have documented security best practices for input validation, especially for user-provided data in example scripts. Fix: Add security best practices documentation to README.md and CONTRIBUTING.md, including guidelines for validating user inputs, handling external data safely, and secure coding practices.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/pytorch/examples shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live pytorch/examples repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/pytorch/examples.

What it runs against: a local clone of pytorch/examples — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in pytorch/examples | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 280 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of pytorch/examples. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/pytorch/examples.git
#   cd examples
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of pytorch/examples and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "pytorch/examples(\\.git)?\\b" \\
  && ok "origin remote is pytorch/examples" \\
  || miss "origin remote is not pytorch/examples (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 280 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~250d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/pytorch/examples"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.