# How the ML-For-Beginners Project Folder Hierarchy Is Organized

> Understand the ML-For-Beginners project folder hierarchy. Explore how docs notebooks labs solutions and resources create a clear learning path from theory to practice in this Microsoft repo.

- Repository: [Microsoft/ML-For-Beginners](https://github.com/microsoft/ML-For-Beginners)
- Tags: internals
- Published: 2026-02-28

---

**The ML-For-Beginners repository organizes curriculum content into top-level directories separating documentation (`docs/`), interactive notebooks (`notebooks/`), hands-on labs (`labs/`), solutions (`solutions/`), and shared resources (`data/`, `images/`, `scripts/`), creating a linear learning flow from theory to practice.**

The **microsoft/ML-For-Beginners** repository employs a pedagogical folder structure designed to guide newcomers through machine learning concepts systematically. Understanding how the project folder hierarchy is organized helps learners navigate from conceptual documentation to executable code efficiently. This guide breaks down each directory's purpose and shows how the components interconnect to form a complete educational platform.

## Top-Level Directory Overview

The repository root contains configuration files and twelve primary directories that serve distinct educational and technical functions. At the highest level, [`README.md`](https://github.com/microsoft/ML-For-Beginners/blob/main/README.md) provides the entry point with navigation instructions, while `LICENSE` defines usage terms. The learning content flows through four sequential stages: static documentation in `docs/`, interactive exploration in `notebooks/`, practical exercises in `labs/`, and verification through `solutions/`.

### Configuration and Environment Files

Two environment specification files accommodate different Python workflows. The [`environment.yml`](https://github.com/microsoft/ML-For-Beginners/blob/main/environment.yml) file defines a Conda environment that pins all required packages for reproducible setups, while [`requirements.txt`](https://github.com/microsoft/ML-For-Beginners/blob/main/requirements.txt) offers a Pip-compatible alternative for virtualenv users. VS Code users benefit from the `.vscode/` directory containing [`settings.json`](https://github.com/microsoft/ML-For-Beginners/blob/main/settings.json), which standardizes the development experience across different machines.

## Core Content Folders

### Documentation (`docs/`)

The `docs/` directory houses the narrative curriculum served via GitHub Pages. Each lesson appears as a Markdown file—for example, [`docs/01-Intro-to-ML.md`](https://github.com/microsoft/ML-For-Beginners/blob/main/docs/01-Intro-to-ML.md)—providing theoretical foundations before learners encounter code. This separation of text and executable content allows the curriculum to function as both a readable website and a structured course outline.

### Interactive Notebooks (`notebooks/`)

Complementing the static docs, the `notebooks/` folder contains Jupyter notebooks illustrating concepts step-by-step. Files like `notebooks/01-Intro-to-ML.ipynb` mirror the documentation structure but embed runnable Python cells for immediate experimentation. You can programmatically discover all available lessons using the repository's consistent naming convention:

```python
from pathlib import Path

repo_root = Path(__file__).resolve().parents[0]
notebook_paths = sorted(repo_root.glob("notebooks/**/*.ipynb"))

for nb in notebook_paths:
    print(nb.relative_to(repo_root))

```

### Hands-On Labs (`labs/`)

After studying documentation and notebooks, learners apply knowledge through practical exercises in the `labs/` directory. Each lesson maintains its own subfolder—for instance, `labs/01-Intro-to-ML/`—containing starter code, prompts, and exercise-specific assets. This folder structure deliberately mirrors the `docs/` and `notebooks/` organization so students can easily locate corresponding materials across different learning modalities.

### Solution References (`solutions/`)

The `solutions/` directory provides completed implementations for every lab exercise, with paths like `solutions/01-Intro-to-ML/` matching their respective lab counterparts. This structure enables self-assessment; learners can compare their work against the reference implementations without spoiling the exercises prematurely.

## Supporting Resources and Configuration

### Shared Datasets (`data/`)

Centralizing all curriculum data in `data/` ensures consistency across lessons. The directory contains sample datasets such as `data/iris.csv` referenced by multiple notebooks and labs. This consolidation eliminates duplication and simplifies data access patterns throughout the repository.

```python
import pandas as pd
from pathlib import Path

DATA_DIR = Path(__file__).resolve().parents[0] / "data"
iris_path = DATA_DIR / "iris.csv"

iris = pd.read_csv(iris_path)
print(iris.head())

```

### Visual Assets (`images/`)

The `images/` folder stores figures and diagrams referenced by both documentation and notebooks. Files like `images/intro.png` support the visual learning components of the curriculum while keeping binary assets separate from source code.

### Utility Scripts (`scripts/`)

Helper scripts for environment setup, data preprocessing, and automated notebook conversion reside in `scripts/`. The [`scripts/setup.sh`](https://github.com/microsoft/ML-For-Beginners/blob/main/scripts/setup.sh) file, for example, automates initial configuration tasks, reducing friction for new learners.

## Automation and Contribution Infrastructure

### GitHub Workflows (`.github/`)

The `.github/` directory contains CI/CD configurations, issue templates, and contribution guidelines under `.github/workflows/`. This hidden directory manages automated testing and community interaction without cluttering the educational content visible to learners.

## Navigating the Learning Flow

The hierarchical design enforces a specific pedagogical sequence. First, learners read the conceptual material in `docs/`, then experiment with the corresponding `notebooks/` file, attempt the exercise in `labs/`, and finally verify their understanding using `solutions/`. This linear progression prevents cognitive overload while maintaining clear boundaries between theory, practice, and assessment.

To establish the required Python environment before starting this workflow, execute the Conda configuration from the repository root:

```bash
conda env create -f environment.yml
conda activate ml-for-beginners

```

Alternatively, Pip users can install dependencies via:

```bash
pip install -r requirements.txt

```

## Summary

- **The `docs/` directory** hosts Markdown curriculum files optimized for GitHub Pages viewing, establishing theoretical foundations for each lesson.
- **The `notebooks/` folder** contains executable Jupyter notebooks that parallel the documentation, enabling interactive experimentation with concepts.
- **The `labs/` and `solutions/` directories** form a practice-and-assessment pair, with matching subfolder structures that isolate exercises from their reference implementations.
- **Shared resources** in `data/`, `images/`, and `scripts/` centralize assets and utilities, preventing duplication across the twelve-lesson curriculum.
- **Environment configuration** through [`environment.yml`](https://github.com/microsoft/ML-For-Beginners/blob/main/environment.yml), [`requirements.txt`](https://github.com/microsoft/ML-For-Beginners/blob/main/requirements.txt), and `.vscode/` ensures consistent tooling regardless of the learner's local setup.

## Frequently Asked Questions

### What is the relationship between the `docs/` and `notebooks/` folders?

Each lesson appears in both locations with matching base filenames—for example, [`docs/01-Intro-to-ML.md`](https://github.com/microsoft/ML-For-Beginners/blob/main/docs/01-Intro-to-ML.md) corresponds to `notebooks/01-Intro-to-ML.ipynb`. The `docs/` version presents narrative explanations optimized for reading, while the `notebook/` version contains executable code cells for hands-on experimentation. This dual-format approach accommodates different learning preferences while maintaining content synchronization.

### How do the `labs/` and `solutions/` directories interact?

The `labs/` directory contains starter code and exercise prompts where learners implement solutions independently. The `solutions/` directory mirrors the `labs/` folder structure exactly, providing completed reference implementations for self-assessment. Both directories follow the lesson numbering convention (e.g., `01-Intro-to-ML/`), making it easy to navigate between an exercise and its answer key without spoiling the learning process.

### Where should I place custom datasets when extending the curriculum?

Place supplementary datasets in the `data/` directory to maintain consistency with the repository's existing structure. The centralized `data/` location is already referenced by utility scripts and notebooks throughout the curriculum, ensuring your additions remain accessible via the same `Path(__file__).parents[0] / "data"` pattern used in the official examples.

### Which environment file should I use for setup?

Use [`environment.yml`](https://github.com/microsoft/ML-For-Beginners/blob/main/environment.yml) if you prefer Conda, as it provides comprehensive dependency pinning including non-Python system libraries. Use [`requirements.txt`](https://github.com/microsoft/ML-For-Beginners/blob/main/requirements.txt) if you work with standard Pip and virtualenv environments. Both files reside in the repository root and contain the same core Python packages (scikit-learn, pandas, matplotlib, jupyter), so the choice depends on your preferred Python environment manager.