The Complete Machine Learning Roadmap — Beginner to Advanced with Python, Mathematics, Projects, and MLOps
Learn machine learning the right way: intuition first, then the math, then production-ready code you can actually ship.
What makes this different? Most tutorials show you
model.fit()and stop. Here, you implement every core algorithm from scratch with NumPy, prove it matches scikit-learn, understand the math behind it, and learn to deploy and monitor it in production. Nothing is a black box.
- Why this repository
- Features
- Learning roadmap
- Course timeline
- Prerequisites
- Installation
- Quick start
- Repository structure
- How each chapter is organized
- Projects
- FAQ
- Contributing
- License
- Acknowledgements
This is a complete, self-paced machine learning course that takes you from zero to production. It is built on four principles:
- Intuition before formulas. Every concept starts with a plain-English explanation and a picture of why it works before any equation appears.
- From scratch, then the library. You build Linear Regression, Logistic Regression, and more with raw NumPy, then compare your version to scikit-learn on accuracy, speed, and memory.
- Everything runs. Every notebook executes top to bottom; every script is tested in CI; every project is production-ready.
- Software engineering counts. Type hints, docstrings, unit tests, linting, and CI/CD are part of the curriculum, not an afterthought.
- ✅ 30 chapters spanning math foundations → classical ML → deep learning → MLOps → deployment.
- ✅ From-scratch NumPy implementations cross-checked against scikit-learn in unit tests.
- ✅ Interactive Jupyter notebooks with visualizations for every major topic.
- ✅ Mathematical intuition — linear algebra, calculus, probability, and information theory explained simply.
- ✅ Real-world datasets — Titanic, MNIST, California Housing, Breast Cancer, IMDB, and more.
- ✅ Hands-on capstone projects — spam detection, churn, fraud, recommendation, LLM apps.
- ✅ Interview preparation — 20 questions with detailed answers per chapter.
- ✅ MLOps & deployment — MLflow, DVC, FastAPI, Docker, ONNX, monitoring, drift detection.
- ✅ Production-grade code — PEP 8, type hints, Black, Ruff, pytest, GitHub Actions.
graph TD
A[Foundations] --> B[Data Skills]
B --> C[Classical ML]
C --> D[Model Craft]
D --> E[Deep Learning]
E --> F[MLOps & Deployment]
F --> G[Capstone Projects]
A -.- A1[Python · Linear Algebra · Statistics · Probability]
B -.- B1[Preprocessing · Visualization · Feature Engineering]
C -.- C1[Regression · Classification · Clustering · Dim. Reduction]
D -.- D1[Evaluation · Ensembles · Tuning · Anomaly · Time Series]
E -.- E1[Neural Nets · CNN · RNN · Transformers · LLMs · RL]
F -.- F1[MLflow · DVC · Docker · FastAPI · ONNX · Monitoring]
G -.- G1[18+ end-to-end real-world projects]
A realistic pace for someone studying part-time (~10 hours/week):
| Phase | Chapters | Focus | Suggested time |
|---|---|---|---|
| 1. Foundations | 01–05 | Python, linear algebra, statistics, probability | 3 weeks |
| 2. Data skills | 06–08 | Preprocessing, visualization, feature engineering | 2 weeks |
| 3. Classical ML | 09–14 | Regression, classification, clustering, PCA | 4 weeks |
| 4. Model craft | 15–19 | Evaluation, ensembles, anomaly, time series, recsys | 3 weeks |
| 5. Deep learning | 20–26 | Neural nets, CNN, RNN, Transformers, LLMs, RL | 5 weeks |
| 6. Production | 27–29 | MLOps, deployment, cloud | 2 weeks |
| 7. Capstones | 30 | Build a portfolio of real projects | 4 weeks |
Total: roughly 6 months part-time. Move faster or slower — the chapters are self-contained.
- Comfort with basic Python (variables, loops, functions). Chapter 02 is a refresher if you're rusty.
- High-school math. All heavier math (calculus, linear algebra) is taught from scratch in chapters 03–05.
- A curious, patient mindset. You'll implement things by hand before using libraries.
No prior machine learning experience is assumed.
Choose one of the following.
# 1. Clone the repository
git clone https://github.com/your-username/machine-learning-mastery.git
cd machine-learning-mastery
# 2. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# 3. Install the from-scratch package + dev tools in editable mode
pip install -e ".[dev]"
# 4. (Optional) install the full stack for every notebook/project
pip install -r requirements.txtconda env create -f environment.yml
conda activate ml-mastery
pip install -e .pytest # all tests should pass
python -c "import mlmastery; print(mlmastery.__version__)"The mlmastery package gives you clean, readable implementations you can learn from:
import numpy as np
from mlmastery import LinearRegression, StandardScaler, train_test_split, r2_score
# Toy problem: y = 3*x1 + 2*x2 + 5
rng = np.random.default_rng(0)
X = rng.normal(size=(200, 2))
y = 3.0 * X[:, 0] + 2.0 * X[:, 1] + 5.0
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=0)
# Standardize features (fit on train only), then train the from-scratch model
scaler = StandardScaler().fit(X_train)
model = LinearRegression(method="normal_equation")
model.fit(scaler.transform(X_train), y_train)
# Evaluate
preds = model.predict(scaler.transform(X_test))
print("R²:", round(r2_score(y_test, preds), 6)) # -> R²: 1.0 (noise-free data)Prefer gradient descent so you can watch it converge?
gd = LinearRegression(method="gradient_descent", learning_rate=0.1, n_iterations=1000)
gd.fit(scaler.transform(X_train), y_train)
print("Final cost:", gd.cost_history_[-1]) # cost decreases every stepmachine-learning-mastery/
├── README.md ← you are here
├── ROADMAP.md ← the full 30-chapter learning path
├── FAQ.md · RESOURCES.md · CHANGELOG.md
├── CONTRIBUTING.md · CODE_OF_CONDUCT.md · SECURITY.md · LICENSE
├── pyproject.toml · requirements.txt · environment.yml
├── .github/workflows/ci.yml ← lint + type-check + test on every push
│
├── src/mlmastery/ ← the from-scratch Python package (installable)
│ ├── linear_regression.py
│ ├── logistic_regression.py
│ ├── metrics.py
│ └── preprocessing.py
│
├── tests/ ← pytest suite (verified against scikit-learn)
├── notebooks/ ← runnable Jupyter notebooks
├── book/ ← 30 chapters of lessons
│ ├── chapter-01-introduction/
│ ├── chapter-10-regression/
│ └── ... (chapters 02–30)
│
├── datasets/ examples/ projects/ interview/ quizzes/ math/
├── images/ assets/ diagrams/
└── scripts/ ← helper tooling (e.g. chapter scaffolder)
Every chapter in book/ follows the same 14-part template so you always
know what to expect. See book/TEMPLATE_CHAPTER.md:
- Theory · 2. Mathematics · 3. Visual explanation · 4. Python implementation ·
- Scikit-learn implementation · 6. From-scratch implementation ·
- Real-world example · 8. Best practices · 9. Common mistakes ·
- Performance discussion · 11. Exercises · 12. Mini project ·
- Interview questions · 14. Further reading
The capstones in book/chapter-30-capstone-projects/
turn theory into a portfolio:
| Project | Core skills |
|---|---|
| Spam Detection | NLP, Naive Bayes, TF-IDF |
| House Price Prediction | Regression, feature engineering |
| Customer Churn | Classification, imbalanced data |
| Fraud Detection | Anomaly detection, precision/recall trade-offs |
| Movie Recommendation | Collaborative filtering, matrix factorization |
| Sentiment Analysis | Transformers, fine-tuning |
| Image Classification | CNNs, data augmentation |
| LLM Application | RAG, embeddings, vector databases |
…and more (fraud, OCR, forecasting, medical diagnosis, chatbot).
See FAQ.md for the full list. A few common ones:
- Do I need a GPU? No, until the deep-learning chapters (20–26), where free Google Colab or Kaggle GPUs are plenty.
- Should I really implement everything from scratch? Yes — once. It's the fastest way to truly understand an algorithm. After that, use the library.
- Is this enough to get a job? Combined with the capstone projects and interview prep, it covers what junior ML/data-science roles expect.
Contributions are welcome and appreciated! Please read
CONTRIBUTING.md and our
CODE_OF_CONDUCT.md first. Good first contributions:
fixing typos, adding exercises, improving explanations, or porting a from-scratch
algorithm to a new chapter using the existing ones as a template.
Released under the MIT License — free to use, modify, and share, including for commercial and educational purposes.
Inspired by the teaching style of Stanford CS229, MIT OpenCourseWare, fast.ai, DeepLearning.AI, and the official Python and scikit-learn documentation. Built by and for the open-source learning community.
⭐ If this repository helps you learn, please star it — it helps others find it. ⭐
Keywords: machine learning, machine learning tutorial, learn machine learning, machine learning roadmap, python machine learning, scikit-learn, deep learning, artificial intelligence, ML projects, MLOps, data science.