# Which Python Libraries Are Banned for Educational Clarity?

> Discover which Python libraries are banned in the ai-engineering-from-scratch curriculum to promote learning foundational algorithms from scratch.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: tutorial
- Published: 2026-06-21

---

**The ai-engineering-from-scratch curriculum bans every Python library except `numpy`, `torch`, `h5py`, `zstandard`, `safetensors`, and the standard library to force students to implement algorithms like backpropagation and attention mechanisms from first principles.**

The rohitg00/ai-engineering-from-scratch repository enforces a strict whitelist policy to maintain educational clarity. By explicitly enumerating which Python libraries are banned for educational clarity, the curriculum ensures that learners build neural networks, tokenizers, and optimizers manually rather than relying on high-level abstractions that obscure core mechanics.

## The Definitive Allow-List in AGENTS.md

The single source of truth for permitted dependencies lives in the **Dependencies** table within [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) at the repository root. According to this file, the allowed Python packages are strictly limited to:

- `numpy`
- `torch`
- `h5py`
- `zstandard`
- `safetensors`
- **stdlib** (Python standard library)

This whitelist approach means that **every Python library not explicitly listed is considered banned**. There are no exceptions; if a package does not appear in this table, importing it violates curriculum policy.

## Common Libraries on the Ban List

While the allow-list is minimal, the ban list encompasses the vast majority of the PyPI ecosystem. Typical examples of banned libraries include:

- **Data manipulation**: `pandas`, `polars`, `dask`
- **Machine learning frameworks**: `tensorflow`, `keras`, `scikit-learn`, `xgboost`, `lightgbm`
- **Visualization**: `matplotlib`, `seaborn`, `plotly`, `bokeh`
- **Computer vision**: `opencv`, `pillow`, `torchvision`
- **NLP utilities**: `torchtext`, `transformers`, `spaCy`, `nltk`
- **Web frameworks and HTTP**: `flask`, `fastapi`, `django`, `requests`
- **Database ORMs**: `sqlalchemy`, `peewee`
- **Web scraping**: `beautifulsoup4`, `scrapy`

If a lesson requires functionality provided by any of these banned packages, students must implement the feature manually using only the allowed libraries or pure Python constructs.

## Enforcement via CI Audit

Compliance is enforced automatically through continuous integration. The repository includes [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py), a linter that scans each lesson file for import statements and validates them against the whitelist.

If a lesson attempts to import a banned module like `pandas` or `tensorflow`, the CI `audit` job fails immediately, blocking the pull request. This mechanism ensures **uniformity** across all lessons and prevents "black-box" dependencies from entering the codebase.

## Code Examples: Allowed vs. Banned

The following examples demonstrate compliant and non-compliant coding patterns found in lesson files like [`phases/01-foundations/01-linear-algebra/code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/01-foundations/01-linear-algebra/code/main.py).

### Compliant NumPy Implementation

Implementing a ReLU activation using only permitted libraries:

```python
import numpy as np

def relu(x: np.ndarray) -> np.ndarray:
    """Rectified Linear Unit using only NumPy."""
    return np.maximum(0, x)

x = np.array([-1.0, 0.5, 2.0])
print(relu(x))          # → [0.  0.5 2. ]

```

### Compliant PyTorch Implementation

Building a linear layer without high-level `torch.nn` utilities:

```python
import torch

def linear(x: torch.Tensor, w: torch.Tensor, b: torch.Tensor) -> torch.Tensor:
    """Simple linear layer without torch.nn.Linear."""
    return x @ w.t() + b

x = torch.randn(3, 4)
w = torch.randn(2, 4)
b = torch.randn(2)
print(linear(x, w, b).shape)   # → torch.Size([3, 2])

```

### Non-Compliant Import (Banned)

The following code would trigger a CI failure:

```python

# ❌ This import is NOT permitted in any lesson

import pandas as pd          # banned – not in AGENTS.md allow-list

```

Attempting to use `pandas` for data preprocessing, `matplotlib` for plotting, or `scikit-learn` for train-test splits requires reimplementing those functionalities manually using `numpy` or standard library tools.

## Summary

- **The allow-list** in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) restricts Python dependencies to `numpy`, `torch`, `h5py`, `zstandard`, `safetensors`, and the standard library.
- **All other libraries** are banned by omission, including popular tools like `pandas`, `scikit-learn`, `matplotlib`, and `tensorflow`.
- **Compliance is enforced** automatically via [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) in the CI pipeline.
- **Educational goal**: Manual implementation of backpropagation, tokenization, and attention mechanisms without hiding logic behind library APIs.

## Frequently Asked Questions

### What happens if I accidentally import a banned library in a lesson?

The CI `audit` job will detect the disallowed import during the pull request process and fail the build. You must remove the banned dependency and reimplement the required functionality using only the allowed libraries before the lesson can be merged.

### Can I request an exception for a specific library like matplotlib for visualization?

No. The curriculum maintains a strict no-exceptions policy to preserve uniformity. If visualization is required, implement a simple ASCII-based plotting function or use `numpy` to format arrays for printing. This constraint reinforces the engineering principle of understanding your data without relying on high-level visualization abstractions.

### Why is torchvision banned when torch is allowed?

While `torch` provides the fundamental tensor operations and autograd engine necessary for building neural networks from scratch, `torchvision` offers high-level datasets, pre-trained models, and image transformations that would short-circuit the learning process. The ban on `torchvision` ensures students implement their own data loaders and image preprocessing pipelines.

### How do I handle data processing without pandas?

Use `numpy` for all tabular data manipulation. Load CSV files using the Python standard library `csv` module or `numpy.genfromtxt`, then perform transformations using `numpy` array operations. For complex data structures, use Python's built-in `dataclasses` or `typing.NamedTuple` instead of pandas DataFrames.