Machine Learning for Beginners — Learner's Guide

A complete, hands-on introduction to classical machine learning. 12 weeks. 26 lessons. Python + R. No deep learning, no heavy math prerequisites. Quizzes, code, and a finished web app at the end.

This guide is written for the learner — someone who wants to study machine learning and actually build things. If you are an educator planning to teach from this curriculum, or a contributor wanting to translate or extend it, read the companion Admin Guide instead.

1. Quick Start

If you want to start in the next ten minutes:

macOS / Linux

git clone --filter=blob:none --sparse https://github.com/microsoft/ML-For-Beginners.git
cd ML-For-Beginners
git sparse-checkout set --no-cone '/*' '!translations' '!translated_images'
python3 -m venv ml-env
source ml-env/bin/activate
pip install jupyter scikit-learn pandas numpy matplotlib seaborn
cd 2-Regression/1-Tools
jupyter notebook notebook.ipynb

Windows (cmd)

git clone --filter=blob:none --sparse https://github.com/microsoft/ML-For-Beginners.git
cd ML-For-Beginners
git sparse-checkout set --no-cone "/*" "!translations" "!translated_images"
python -m venv ml-env
ml-env\Scripts\activate
pip install jupyter scikit-learn pandas numpy matplotlib seaborn
cd 2-Regression\1-Tools
jupyter notebook notebook.ipynb

Windows (PowerShell)

git clone --filter=blob:none --sparse https://github.com/microsoft/ML-For-Beginners.git
cd ML-For-Beginners
git sparse-checkout set --no-cone '/*' '!translations' '!translated_images'
python -m venv ml-env
.\ml-env\Scripts\Activate.ps1
pip install jupyter scikit-learn pandas numpy matplotlib seaborn
cd 2-Regression\1-Tools
jupyter notebook notebook.ipynb

Expected output when Jupyter starts:

[I 2026-04-23 10:15:03.123 ServerApp] Jupyter Server is running at:
[I 2026-04-23 10:15:03.123 ServerApp]     http://localhost:8888/?token=abc123...

Your default browser should open on that URL. Click the notebook file name in the tree, then step through cells with Shift+Enter.

Tip

The --sparse + sparse-checkout set commands skip the translations/ and translated_images/ directories, cutting clone size by roughly 95%. You only need them if you are reading the course in a non-English language.

Note

You don't have to start at lesson 1. Each lesson group (Regression, Classification, Clustering, …) is self-contained. Pick the topic you need.

2. What You Will Learn

This is a curriculum about classical machine learning. That means:

• You will use Scikit-learn, the de-facto Python library for traditional ML, for almost every exercise.
• You will work with Pandas for tabular data and Matplotlib / Seaborn for plots.
• You will not train deep neural networks here. (Microsoft publishes a separate AI for Beginners curriculum for that.)
• Every lesson is project-based — you build something you can show someone.

By the time you finish the curriculum, you will have:

• Built regression models that predict numerical values (pumpkin prices).
• Built classification models that place inputs into categories (world cuisine from ingredients).
• Built clustering models that find natural groups in unlabelled data (Nigerian music taste clusters).
• Built an NLP pipeline that analyses sentiment in hotel reviews.
• Forecasted a time series with ARIMA and SVR (world electricity usage).
• Trained a reinforcement-learning agent (Peter avoiding the wolf via Q-Learning; CartPole via OpenAI Gym).
• Deployed a trained model behind a Flask web UI that takes form input and returns a prediction (UFO sighting country).

Important

This is classical ML, taught using real datasets from many different cultures. Pumpkins in North America, cuisine from Asia, music from Nigeria, hotels in Europe. The data is deliberate — it forces you to think about fairness and bias early.

3. Curriculum at a Glance

The curriculum is a 26-lesson, 12-week walk through seven topic areas plus a real-world postscript.

A full numbered lesson table (with authors and R/Python links) lives in the repository's root README.md.

Choose your own pace

• Fast track — one lesson group per week (≈4 weeks). Skip the R path, skip the reinforcement learning postscript.
• Standard — two lessons per week over 13 weeks, matching the curriculum's design.
• Slow / deep — one lesson per week plus all assignments, all challenges, the R path where it exists, and the postscript. About 6 months.

Each lesson was designed to stand alone, so jumping between groups is fine once you have the Regression basics (lessons 5-8) under your belt.

4. Before You Start

This curriculum teaches machine learning, not Python or R from scratch. You will have a much easier time if you already know:

• Python basics — variables, functions, lists, dictionaries, import.
• A little NumPy and Pandas — at least "how do I load a CSV and look at the first rows?".
• The command line — opening a terminal, changing directories, running commands.

If any of that is shaky, the curriculum itself will not stop you, but lesson 5 (Regression → Tools) assumes you can open a Jupyter notebook and run a cell. Spend an afternoon on a Python primer before starting if you need to.

What the curriculum does NOT cover

• Deep learning, neural networks, PyTorch, TensorFlow — these are in the sibling AI for Beginners curriculum.
• MLOps (model deployment at scale, CI/CD for ML, model monitoring).
• Cloud ML services (beyond the single Azure Static Web Apps deployment for the quiz app).
• Production data engineering (ETL, feature stores).

It is a classical ML curriculum. Keep that scope in mind when picking your next step after finishing.

5. Installation

5.1 The Python path (primary)

Every lesson in this curriculum is authored in Python first. Setting up the Python environment covers 90% of the exercises.

Minimum for lessons 1–4

# Introduction lessons are mostly reading + videos + quizzes.
# You can complete them with just a web browser. No install needed.

Minimum for lessons 5–28

# Create an isolated environment so this curriculum doesn't interfere
# with other Python projects on your machine.
python3 -m venv ml-env

# Activate it (repeat each new terminal session):
# macOS/Linux:
source ml-env/bin/activate
# Windows:
ml-env\Scripts\activate

# Install the core stack used across the curriculum:
pip install jupyter scikit-learn pandas numpy matplotlib seaborn

# Verify:
python -c "import sklearn, pandas, numpy; print(sklearn.__version__)"

Expected output:

1.5.2

Plus Flask (lesson 9)

pip install flask

Plus OpenAI Gym (lesson 25)

pip install gym

Tip

Always use a virtual environment. Installing packages into your system Python is a fast route to version conflicts six lessons from now. venv is built into Python 3 — no extra tools needed.

Note

The repository does not ship a top-level requirements.txt. Each lesson installs only what it needs. The only lesson with a pinned requirements file is the Flask web app in 3-Web-App/1-Web-App/solution/web-app/requirements.txt.

5.2 The R path (optional, lessons 5–15)

Several regression, classification, and clustering lessons have an R track in solution/R/ as a companion to the Python notebook. If you already know R, you can follow those instead.

# In your R console:
install.packages(c("tidyverse", "tidymodels", "caret"), dependencies = TRUE)

Each R lesson is an .Rmd (R Markdown) file with a rendered .html alongside it. Open the .Rmd in RStudio or VS Code with the R extension.

Note

Not every lesson has an R version. The Introduction, Web App, NLP, Time Series, and Reinforcement Learning tracks are Python-only. Check the solution/R/ folder for each lesson — if it's missing, that lesson is Python-only.

5.3 VS Code integration (recommended)

If you prefer VS Code over Jupyter's browser UI:

# Install the Python and Jupyter extensions from the VS Code marketplace.
# Then, inside your venv:
pip install ipykernel
python -m ipykernel install --user --name=ml-env --display-name="Python (ml-env)"

Open any notebook.ipynb directly in VS Code. At the top-right, click Select Kernel → Python (ml-env).

6. How a Lesson Works

Every lesson in the curriculum follows the same rhythm. Learn this rhythm once and you can navigate all 26 lessons confidently.

Important

The solution code is always in a solution/ sub-folder. Attempt the exercise first — don't read the solution until you are stuck or finished. Looking at the answer before trying is the fastest way to memorise the surface and learn nothing underneath.

6.1 Pre-lecture and post-lecture quizzes

Quizzes are served from an external hosted quiz app at https://ff-quizzes.netlify.app/en/ml/. Clicking the quiz link in a lesson README opens it in your browser.

Caution

The quiz service runs on Netlify, outside this repository. If you are on a restricted network or the service is down, the quizzes will not load. You can run the quiz app locally as a fallback (see section 10).

6.2 The solution/, working/, and sub-folder convention

Many lessons — especially Time Series and Classification — have multiple sub-folders inside them. The layout you'll see:

7-TimeSeries/2-ARIMA/
├── README.md             # The lesson you read
├── notebook.ipynb         # The exercise you work through
├── assignment.md          # Extended practice
├── solution/              # Fully-worked reference answer
│   └── notebook.ipynb
└── working/               # A stub you can edit without touching the lesson
    └── notebook.ipynb

Work in working/. Peek at solution/ only when you need to.

7. Running the Regression / Classification / Clustering / NLP / Time-Series Lessons

These are the five lesson groups where you run Jupyter notebooks against Scikit-learn. The workflow is identical for all of them.

# 1. Activate your env.
source ml-env/bin/activate          # macOS/Linux
ml-env\Scripts\activate              # Windows

# 2. Change into the specific lesson folder.
cd 2-Regression/3-Linear

# 3. Launch Jupyter on the lesson notebook.
jupyter notebook notebook.ipynb

Expected output:

[I 2026-04-23 10:42:11.042 ServerApp] http://localhost:8888/tree

Jupyter opens in your browser. Click notebook.ipynb in the file tree. Shift+Enter runs the current cell.

Tip

Always run Jupyter from the lesson's own directory. Relative paths inside the notebook (e.g. pd.read_csv('../data/pumpkins.csv')) assume the current working directory is the lesson folder.

7.1 Typical cell patterns you will see

# Import stack at the top:
import pandas as pd
import numpy as np
from sklearn.linear_model import LinearRegression
from sklearn.model_selection import train_test_split
from sklearn.metrics import mean_squared_error
import matplotlib.pyplot as plt
%matplotlib inline

# Data load:
df = pd.read_csv('../data/pumpkins.csv')
df.head()

# Train / test split + fit:
X = df[['Month', 'DayOfYear']]
y = df['Price']
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

model = LinearRegression()
model.fit(X_train, y_train)

preds = model.predict(X_test)
print('RMSE:', np.sqrt(mean_squared_error(y_test, preds)))

If a cell like the one above fails, jump to section 13.

8. Running the Web App (Lesson 9)

Lesson 9 (3-Web-App/1-Web-App/) is where you wrap a trained Scikit-learn model behind a Flask web server and take a form submission from the user.

cd 3-Web-App/1-Web-App/solution/web-app

# Install the Flask app's own pinned deps (separate from the core ML stack):
pip install -r requirements.txt

# Start the dev server:
python app.py

Expected output:

 * Serving Flask app 'app'
 * Debug mode: on
 * Running on http://127.0.0.1:5000

Open http://localhost:5000, fill in the UFO-sighting form, and submit. The app loads the pre-trained ufo-model.pkl file, runs model.predict(), and maps the numeric class to a country name:

countries = ["Australia", "Canada", "Germany", "UK", "US"]
return render_template("index.html", prediction_text="Likely country: {}".format(countries[output]))

The requirements.txt for this lesson is minimal:

scikit-learn
pandas
numpy
flask

Warning

The Flask app.run(debug=True) default is intended for local development only. Do not expose it to the public internet. The web app lesson is deliberately simple — it has no authentication, no input sanitisation, and it serves every request as the same user. See the Admin Guide's Teaching-project security properties section for the full list.

9. Running the R Lessons (Optional)

If you want to follow an R path for regression, classification, or clustering:

cd 2-Regression/1-Tools/solution/R

# Option A — open in RStudio:
# File → Open File → lesson_1.Rmd → Knit button

# Option B — render from the command line:
Rscript -e "rmarkdown::render('lesson_1.Rmd')"

This produces lesson_1.html which you can open in any browser.

To run R inside Jupyter instead of RStudio:

# In R:
install.packages('IRkernel')
IRkernel::installspec(user = TRUE)

Then in Jupyter, File → New → Notebook → R.

Note

Pre-rendered .html versions of every R lesson are committed to the repo, so you can read the lessons without installing R at all. You only need R if you want to execute the code yourself.

10. Running the Quiz App Locally

The quiz app is a small Vue.js application at quiz-app/. It ships with all 52 quiz definitions (three questions each, pre- and post-lecture for each of the 26 lessons).

cd quiz-app
npm install
npm run serve

Expected output:

  App running at:
  - Local:   http://localhost:8080/
  - Network: http://192.168.1.42:8080/

Open http://localhost:8080 and pick a quiz.

Tip

Running the quiz app locally is the answer when the hosted ff-quizzes.netlify.app service is unreachable. It is an exact mirror of the online version.

11. Offline and PDF Access

11.1 Read the curriculum as a website

The whole curriculum is authored as Markdown and rendered by Docsify — a zero-build static-site generator that reads the markdown files directly at runtime.

# Install Docsify globally (one time):
npm install -g docsify-cli

# Serve the curriculum on port 3000:
cd ML-For-Beginners
docsify serve

Expected output:

Serving /path/to/ML-For-Beginners now.
Listening at http://localhost:3000

Open http://localhost:3000. Sidebar navigation, search, and pretty rendering all work without any build step.

11.2 PDF of the whole curriculum

A pre-built PDF of the full curriculum is published at https://microsoft.github.io/ML-For-Beginners/pdf/readme.pdf.

You can regenerate it yourself:

npm install        # Uses the root package.json (docsify-to-pdf)
npm run convert    # Writes pdf/readme.pdf

12. Learning in Your Language

The curriculum ships with machine-generated translations in 50+ languages. Each supported language lives at translations/<lang-code>/ with a full mirror of every lesson README, and each lesson's illustrations are re-rendered (with translated captions) into translated_images/<lang-code>/.

The translation system is fully automated (see the Admin Guide for details). The relevant fact for a learner: the English content is canonical. Translations are re-generated every time the English source changes, so any differences you see in a translated page are quirks of the automated translator, not intentional edits.

12.1 Browsing to your language

From the root README.md, click your language in the Multi-Language Support table. You will land at translations/<lang>/README.md and can navigate from there.

12.2 Cloning only your language (saves ~95% of the download)

git clone --filter=blob:none --sparse https://github.com/microsoft/ML-For-Beginners.git
cd ML-For-Beginners

# Keep root files + only your language (example: French):
git sparse-checkout set --no-cone '/*' '!translations' '!translated_images' 'translations/fr' 'translated_images/fr'

Note

The list of supported languages is kept in the root README.md. If your language is missing, you can contribute one — see the Admin Guide's Translation System section for the workflow.

13. Troubleshooting

Solutions below are grounded in the repository's own TROUBLESHOOTING.md plus real user issues in the GitHub tracker.

Error: python: command not found

Cause: Python is not installed, or not on PATH.

Solution: Install Python 3.8+ from python.org. On macOS/Linux try python3 --version — many systems ship Python 3 as python3, not python.

Prevention: Prefer python3 in all shell commands on macOS/Linux to avoid ambiguity with a stale Python 2.

Error: ModuleNotFoundError: No module named 'sklearn'

Cause: Scikit-learn is not installed in the active environment, or Jupyter is running in a different environment than where you pip install-ed.

Solution:

pip install scikit-learn pandas numpy matplotlib seaborn

If you still see the error in Jupyter, the notebook is using a different kernel:

pip install ipykernel
python -m ipykernel install --user --name=ml-env --display-name="Python (ml-env)"
# In Jupyter: Kernel → Change Kernel → Python (ml-env)

Prevention: Always activate your venv before starting Jupyter.

Error: FileNotFoundError: [Errno 2] No such file or directory: '../data/pumpkins.csv'

Cause: You started Jupyter from the wrong directory. Notebook relative paths are relative to the notebook, but Jupyter's working directory is wherever you launched it.

Solution:

cd 2-Regression/2-Data      # Always from the lesson folder.
jupyter notebook notebook.ipynb

Prevention: Close the terminal in the repo root before starting work on a lesson. Open a new terminal inside the lesson folder.

Error: ConvergenceWarning: Maximum number of iterations reached

Cause: Logistic Regression (and some other classifiers) failed to converge in the default 100 iterations. This is a warning, not a hard failure, but the model's coefficients are not stable.

Solution:

from sklearn.linear_model import LogisticRegression
from sklearn.preprocessing import StandardScaler

scaler = StandardScaler()
X_scaled = scaler.fit_transform(X)
model = LogisticRegression(max_iter=1000)
model.fit(X_scaled, y)

Scale your features and raise max_iter. Scaling alone usually fixes it.

Prevention: Any lesson that trains a linear model on unscaled numerical features will trigger this. Add a StandardScaler step when you see it.

Error: Kernel dies when loading a large CSV

Cause: The file is too big to fit in memory comfortably — common on laptops with 8 GB RAM.

Solution: Load in chunks:

for chunk in pd.read_csv('large_file.csv', chunksize=10000):
    process(chunk)

Or load only the columns you actually need:

df = pd.read_csv('file.csv', usecols=['col1', 'col2'])

Prevention: Peek at df.info(memory_usage='deep') after loading. If a single DataFrame is using >1 GB, reduce dtypes (int64 → int32) or sample.

Error: Plots not showing in Jupyter

Cause: Inline plotting not enabled, or plt.show() missing at the end of the cell.

Solution:

%matplotlib inline
import matplotlib.pyplot as plt
plt.plot(data)
plt.show()

Prevention: Most lesson notebooks set %matplotlib inline at the top. If you edit a cell and forget to include it, put it back.

Error: UnicodeDecodeError when reading a CSV

Cause: The file uses a non-UTF-8 encoding. Common in Excel exports.

Solution:

df = pd.read_csv('file.csv', encoding='latin-1')

Or:

df = pd.read_csv('file.csv', encoding='utf-8', errors='ignore')

Prevention: Specify encoding='utf-8' explicitly when you write CSVs of your own.

Error: npm install fails in quiz-app/

Cause: Stale node_modules or corrupted package-lock.json.

Solution:

cd quiz-app
rm -rf node_modules package-lock.json
npm cache clean --force
npm install
# If still failing:
npm install --legacy-peer-deps

Prevention: Node ≥ 18 is recommended (the repo was last tested on recent Node LTS).

Error: Polynomial regression plot looks like a zigzag line (tracked as issue #968)

Cause: The polynomial regression notebook plots the predictions in dataset order without sorting by the X axis, so the plotted line visits points in insertion order rather than left-to-right.

Solution: Sort X (and the matching predictions) before plotting:

order = X_test.flatten().argsort()
plt.plot(X_test.flatten()[order], preds[order])

Error: Broken link in a lesson README (tracked as issue #927)

Cause: External links age. The curriculum is ~4 years old; some Microsoft Learn URLs have moved.

Solution: Search the Microsoft Learn catalogue or the target site for the replacement. If you want the fix upstreamed, open an issue (or better, a PR).

Error: Port 8080 is already in use (quiz app)

Solution:

npm run serve -- --port 8081

Error: Discord link or external quiz service unreachable

Cause: You are on a network that blocks Netlify, Discord, or Microsoft domains. Or the services are temporarily down.

Solution: Run the quiz app locally (section 10). For Discord, the curriculum is usable without it — community support is a nice-to-have, not a requirement.

14. Frequently Asked Questions

Q: Is this curriculum free? Yes. MIT-licensed, no account required, no paywall.

Q: Do I need a Microsoft account? No. You don't need an Azure account or a GitHub account to learn. You do need a GitHub account if you want to fork the repo, submit PRs, or deploy the quiz app to Azure.

Q: How long does the full curriculum take? The authors designed it for 12 weeks at two lessons per week. That is about 6–10 hours per week including quizzes, challenges, and assignments.

Q: Do I need a GPU? No. This curriculum is classical ML — everything runs on CPU, including the reinforcement learning lessons. An older laptop with 8 GB RAM is plenty.

Q: Can I do this without R? Yes. The primary track is Python. R is offered as a companion for lessons 5–15 only, and is entirely optional.

Q: Can I do this without Python? Not easily. Every lesson's exercises and solutions are Python-first. R covers roughly half the hands-on exercises and none of the NLP, Time Series, or RL content. You would be using this curriculum primarily as concept material and skipping the coding exercises.

Q: Where do the datasets come from? Each lesson includes its own dataset in the lesson's data/ folder. Datasets are public and non-sensitive — pumpkin prices from US Department of Agriculture, a cuisine dataset, a Nigerian Spotify music dataset, a European hotel reviews dataset, etc.

Q: Are there video walkthroughs? Yes, for many lessons. Find them inline in the lesson READMEs or on the ML for Beginners YouTube playlist.

Q: Why so much focus on fairness (lesson 3)? Because ML systems affect real people, and the earlier you internalise that models can encode and amplify bias, the better your downstream work will be. Lesson 3 is deliberately placed before you build anything.

Q: Why doesn't this cover deep learning? Deep learning is covered in AI for Beginners. Classical ML on its own is still the right tool for a huge class of problems (small datasets, interpretable models, tabular data). The authors chose depth on classical ML over a shallow sampling of everything.

Q: What do I study next? After finishing the postscript, natural next steps are AI for Beginners (deep learning), Data Science for Beginners (more data-centric), or a Kaggle competition where you apply what you learned to unfamiliar data.

Q: I found a bug / broken link / typo. What do I do? Open a GitHub issue at https://github.com/microsoft/ML-For-Beginners/issues, or better, a pull request with the fix. The Admin Guide's Contributing section explains the PR process.

Q: Can I translate a lesson into my language? Translations are machine-generated via GitHub Actions. Do not edit files under translations/ — your changes will be overwritten on the next sync. If you want to improve translation quality, see the Admin Guide's Translation System section — the path is to improve the upstream Co-op Translator, not to hand-edit the output.

Q: Can I use this in my classroom? Yes. See for-teachers.md in the repo, or the Admin Guide's Classroom Use section. GitHub Classroom is the recommended path.

Q: Can I write a blog post / book / course based on this? The curriculum is MIT-licensed, so yes, attribution required. If your derivative work is also free, the authors appreciate a link back to the original.

Q: Is there a Discord? Yes — the Microsoft Foundry Discord has an #ml-for-beginners channel. It's optional; the curriculum is self-contained.

Q: How recent is this? The curriculum was first published in 2021 and receives ongoing updates. Machine learning fundamentals don't change — the concepts taught here (regression, classification, clustering) are the same today as they were ten years ago. Some library APIs (Scikit-learn) have evolved but the lessons still run with current versions.

15. Reference

15.1 Complete lesson inventory

15.2 Commands cheat sheet

# Activate env (every new terminal session):
source ml-env/bin/activate          # macOS/Linux
ml-env\Scripts\activate              # Windows

# Run a lesson:
cd <lesson-folder>
jupyter notebook notebook.ipynb

# Run the Flask web app:
cd 3-Web-App/1-Web-App/solution/web-app
pip install -r requirements.txt
python app.py                        # http://localhost:5000

# Run the quiz app:
cd quiz-app
npm install
npm run serve                        # http://localhost:8080

# Serve the curriculum as a site:
docsify serve                        # http://localhost:3000 (from repo root)

# Regenerate the PDF:
npm install
npm run convert                      # writes pdf/readme.pdf

15.3 Key external links

• Curriculum home on GitHub
• Microsoft Learn collection
• YouTube playlist
• GitHub Discussions
• Microsoft Foundry Discord — #ml-for-beginners
• Online quiz app
• Pre-built PDF
• Companion: AI for Beginners (deep learning)
• Companion: Data Science for Beginners

15.4 Recommended reading order for first-time learners

1. README.md (you've probably already skimmed it).
2. 1-Introduction/ — all four lessons. Do the quizzes.
3. 2-Regression/ — end to end. This is where you confirm your tooling works and build your first real model.
4. 3-Web-App/ — ships a working Flask app. Start here if you want to see something visible sooner.
5. Pick your path from here: Classification → Clustering → NLP → Time Series → Reinforcement, in roughly that order.
6. 9-Real-World/ — the postscript. Read it once you've built a few models; the real-world context lands better.