PyCaret

Overview

PyCaret is a low-code machine learning library for Python. It wraps data preparation, model comparison, tuning and evaluation into a small set of short commands, so a first working model on a table can take a few lines of code instead of a few hundred. It is best known for one idea: train many standard models on the same data with the same settings and show them in a single ranked table.

PyCaret is most useful for fast prototyping and for building a baseline before more careful work. It sits on top of well-known libraries such as scikit-learn, XGBoost, LightGBM and CatBoost, and it hides most of the plumbing. That convenience has a cost: you give up some control, and a quick leaderboard result is not a finished model. This article explains how PyCaret works, where it helps, where it misleads, and how it relates to newer models that learn directly from raw tables, such as the ones described on the model research page.

What it is

PyCaret is an open-source Python library that packages a typical machine learning workflow for tables. A tabular workflow usually has the same stages every time: load data, clean it, encode categories, scale numbers, split into train and test sets, fit several models, compare them, tune the best one, check it, and save it. PyCaret turns each stage into one function call.

Think of it like a meal kit. A meal kit does not teach you to cook, and it does not give you every possible ingredient. It gives you pre-measured portions and a clear recipe so dinner is ready fast. PyCaret gives you pre-configured steps and a clear order so a model is ready fast.

The main modules

PyCaret groups its functions by task type. Each task type has its own module with a similar set of function names.

• Classification: predict a category, such as churn or no churn.
• Regression: predict a number, such as price or demand.
• Clustering: group rows without labels.
• Anomaly detection: flag rows that look unusual.
• Time series: forecast a numeric series over time.

The shared names are what make the library feel low-code. Once you know setup, compare_models, tune_model, finalize_model and predict_model, you can move between tasks with little new learning.

What "low-code" means here

Low-code does not mean no-code. You still write Python, and you still need to understand your data. What shrinks is the amount of boilerplate. Instead of building a pipeline object by hand, you describe the problem in one call and let the library build it. You can still reach inside and change things when you need to.

Where it came from

PyCaret was created as an open-source project in the early 2020s. Its design was inspired by the "caret" package in the R language, whose name stands for classification and regression training. Caret gave R users one consistent interface to many modelling packages. PyCaret aimed to give Python users the same convenience.

The wider context is the rise of automated machine learning, often called AutoML. As more people needed models and fewer had time to write full pipelines, tools appeared that automated common steps. Some tools focus on heavy automated search. PyCaret took a lighter path. It focuses on making each step short and visible, and it leaves the decisions to the user.

Over time the library grew from classification and regression to cover clustering, anomaly detection and time series. It also added experiment logging hooks, so runs could be tracked with tools such as MLflow. Details of specific version numbers change often, so check the project documentation for the current feature set.

How it works

PyCaret follows a fixed rhythm. Each step builds on the previous one, and most of them are one function call.

Step 1: setup

The setup call is the foundation. You pass in a data frame and the name of the target column. PyCaret then does several things at once:

1. It infers the type of each column (numeric, categorical, date and so on).
2. It splits the data into training and hold-out parts.
3. It builds a preprocessing pipeline, which can impute missing values, encode categories, scale numbers and more.
4. It prepares cross-validation folds.
5. It records the whole configuration so later calls reuse it.

Imagine a kitchen where the chef lays out every tool and ingredient before cooking. Setup is that preparation. Nothing is cooked yet, but everything that later steps need is in place and labelled.

Step 2: compare_models

The compare_models call trains a library of standard algorithms, scores each one with cross-validation, and prints a sorted table. The table lists metrics such as accuracy, area under the curve, recall, precision and F1 for classification, or error measures for regression.

This is the signature feature. It answers a common first question: "Which family of models works reasonably well on this table?" Think of a taste test where you try ten sauces on the same pasta, then pick the two worth refining.

Step 3: create_model and tune_model

After the comparison, you may choose one algorithm and call create_model to train it alone. Then tune_model searches over its hyperparameters. Hyperparameters are settings you choose before training, such as tree depth or learning rate. The tuning step uses a search strategy to try combinations and keep the best.

By default the search can use a random or grid approach. PyCaret can also hand the search to dedicated tuning libraries such as Optuna, and the parallel tuner Ray Tune is another option in that family. Check the documentation for the exact options in your installed version.

Step 4: ensembling and blending

PyCaret offers helpers to combine models. Bagging trains the same model on different samples. Boosting adds models in sequence, each fixing earlier errors. Blending averages the predictions of several different models. Stacking trains a second model on the outputs of the first ones. These are single calls, which makes experimenting cheap.

Step 5: evaluate and interpret

The plot_model and evaluate_model functions draw standard diagnostics: confusion matrix, ROC curve, feature importance, residual plots and more. The interpret_model function can produce explanations based on SHAP. You can also explain single predictions with local methods such as LIME outside the library.

Step 6: finalize and deploy

finalize_model refits the chosen pipeline on all the data, including the hold-out part. save_model writes the whole pipeline, including preprocessing, to a file. load_model and predict_model bring it back for scoring. Because the preprocessing is stored with the model, new data goes through the same steps as training data. That removes a common source of bugs.

Key concepts and terms

A worked example

The example below uses a small made-up table about customer subscriptions. The host and file names are placeholders.

import pandas as pd
from pycaret.classification import (
    setup, compare_models, tune_model,
    finalize_model, predict_model, save_model, plot_model,
)

# Load a table with columns such as plan_age, usage_hours,
# support_tickets, region and a binary column named "churned".
df = pd.read_csv("customers.csv")

# 1. Describe the problem
exp = setup(
    data=df,
    target="churned",
    session_id=42,        # fixes the random seed
    fold=5,               # 5-fold cross-validation
    normalize=True,       # scale numeric columns
)

# 2. Try many standard models
best = compare_models(sort="AUC", n_select=3)

# 3. Tune the top one
tuned = tune_model(best[0], optimize="AUC", n_iter=20)

# 4. Look at diagnostics
plot_model(tuned, plot="confusion_matrix")
plot_model(tuned, plot="feature")

# 5. Refit on all data and score new rows
final = finalize_model(tuned)
new_rows = pd.read_csv("new_customers.csv")
scored = predict_model(final, data=new_rows)

# 6. Save the full pipeline
save_model(final, "churn_pipeline")

Reading the result

After compare_models, you see a table with one row per algorithm. Suppose the top three are all within a small gap of each other. That is a signal, not a verdict. When scores are that close, the ranking may flip on a different split. A careful reader would repeat the run with another seed, look at the spread across folds, and prefer the simpler model if the gap is within noise.

A numeric walk-through of cross-validation

Say you have 1,000 rows and use 5 folds. Each fold holds out 200 rows. The model trains on the other 800 and is scored on the 200. After five rounds you have five scores. If they are 0.81, 0.83, 0.80, 0.82 and 0.84, the mean is 0.82. The leaderboard shows that mean. The spread, here about 0.04 from lowest to highest, tells you how stable the estimate is. A model with a mean of 0.83 and a spread of 0.10 is less trustworthy than one with a mean of 0.82 and a spread of 0.02.

Strengths and limitations

Strengths

• Very fast to a first result. A full baseline can fit in a dozen lines.
• One consistent interface across classification, regression, clustering, anomaly detection and time series.
• The pipeline travels with the model, which cuts train and serve mismatches.
• Built-in plots make diagnostics easy for beginners.
• It exposes the underlying scikit-learn style objects, so you can drop down to lower-level code.
• Good for teaching, because each step has a clear name.

Limitations

• Convenience can hide choices. Default imputation, scaling and encoding may not fit your data.
• A leaderboard on one split can be optimistic, especially with small data.
• Heavy defaults may be slow on large tables, since it trains many models.
• It does not replace domain thinking. It will happily model a leaked column.
• Dependency management can be demanding, because it relies on many other libraries with their own version needs.
• Deep learning and custom architectures are outside its core scope.
• Fine control over time-aware validation, grouped splits or unusual metrics may need extra work.

Where it can mislead

The most common trap is trusting the top row of the leaderboard. A gap of one point in accuracy may be noise. Another trap is data leakage: if a column secretly contains the answer, such as a field filled in after the outcome, every model will score very well and none will work in production. PyCaret cannot know this. You must.

How it compares with alternatives

PyCaret is not a competitor to boosted trees. It uses them. It is closer to a front door that lets you try many of them with one command. If you need to tune one model deeply, you will likely move to a dedicated library. If you need a custom pipeline in production, you may export what PyCaret chose and rebuild it in plain scikit-learn code.

Role in tabular foundation models

Tabular foundation models are models trained on very many tables so that they can learn patterns across datasets. They try to work directly on a raw table, with rows, columns of mixed types, missing values and often no helpful column names. PyCaret does not train such models, but it relates to them in several practical ways.

PyCaret as the classical baseline

When someone claims that a pre-trained table model works well, the fair question is "compared with what?" A quick PyCaret run gives a standard answer: here is what a tuned set of common models achieves on the same split. Baselines like this are the usual yardstick in benchmark work, as discussed on the benchmarks page. A tabular foundation model that cannot beat a quick comparison of trees and linear models is not yet earning its keep on that dataset.

Different philosophy: per-dataset fitting versus in-context learning

PyCaret follows the classic approach. For every new table, you fit new models, tune them and score them. A tabular foundation model such as TabPFN or TabICL follows another path. It is pre-trained once, often on large collections of synthetic tables, then it reads your training rows as context and predicts new rows in a single forward pass. There is no per-dataset gradient training. In everyday terms, PyCaret hires a new apprentice for each job and trains them from scratch. An in-context model is a veteran who has seen thousands of similar jobs and only needs to look at your examples.

Preprocessing is where the two worlds differ most

PyCaret builds explicit preprocessing: imputation, encoding, scaling. Tabular foundation models try to fold much of this into the model itself.

• Mixed types: PyCaret encodes categories before modelling. A foundation model may learn to handle numbers and categories through its input encoders.
• Missing values: PyCaret fills gaps with a rule such as the mean or the most frequent value. A foundation model can learn what a gap means, and in some designs can be trained with a masked-cell objective, where cells are hidden and the model must recover them. See imputation networks for the related idea.
• No column names: PyCaret uses names to infer types and to read feature importance. A model that must work with unnamed or poorly named columns cannot lean on names, so it relies on the values and the relationships between columns.
• Row and column structure: A classic model sees a flat vector per row. A table model can treat rows and columns as two axes of attention and reason across both.

Imputation and anomaly detection

PyCaret includes simple imputation options and an anomaly detection module built on standard detectors. These are useful reference points. A foundation model that imputes by predicting masked cells can be tested against a PyCaret-style simple imputer on the same missing-value pattern. Likewise, a model that scores row-level oddness can be compared against the detectors in the anomaly detection page. Careful comparisons use the same masks, the same splits and the same metrics.

Where a quick comparison tool still helps

Even in a world with strong pre-trained table models, a quick comparison tool has a job. It helps decide whether the problem needs a heavy model at all. If a linear model and a boosted tree both give nearly the same score, extra complexity is unlikely to pay off. It also helps check for leakage and for label noise before any expensive model is trained. For deeper context on how table models are built and evaluated, see the architecture page.

Continual learning and drift

PyCaret models are usually retrained from scratch when data changes. Continual learning research asks how a model can absorb new data without forgetting what it knew. PyCaret does not address this directly. In production, teams use scheduled retraining and monitor for drift, comparing new data against old distributions. A tabular foundation model may offer an alternative path, since adding fresh context rows can update predictions without retraining weights, though this has its own limits.

Sector and semantic classification

Another use of table models is to classify what a table or a column represents, for example whether a table looks like finance, retail or telecom data. This is a semantic task rather than a prediction task. PyCaret does not target it. You could use its classification module on hand-built features that describe a column, but that is a manual route compared with a model that reads the table directly.

Practical guidance and best practices

Start with the question, not the library

Write down the target, the time at which the prediction is made, and which columns would be known at that moment. Remove anything that would not be available. This one habit prevents most leakage.

Set a seed and keep it

Always pass a session id so runs can be repeated. Report results over several seeds when scores are close.

Choose the metric that matches the cost

Accuracy is a poor guide when classes are imbalanced. If only five percent of customers churn, a model that always says "no churn" is 95 percent accurate and useless. Pick recall, precision, F1 or area under the curve depending on what a mistake costs.

Check the data types it inferred

After setup, read the summary of detected types. A numeric code such as a postal code may be treated as a number when it is really a category. Fix the type explicitly.

Respect time order

If rows are ordered in time and you predict the future, do not use random folds. Use a time-aware split so the model never trains on data from after the rows it is scored on. Check the documentation for how to set this in your version.

Use groups when rows are not independent

If several rows belong to the same customer or device, random splits can place one customer in both train and test. Scores then look better than they will be in practice. Use grouped splitting.

Tune after you choose

Compare first with defaults, choose a family, then tune. Tuning every model is slow and rarely changes the ranking much.

Keep a record

Log experiments with a tracker such as MLflow. You will thank yourself when someone asks which settings produced last month's model.

Export and test

Before going live, test the saved pipeline on a few rows by hand, including rows with missing values and unseen categories. Confirm that predictions match what you saw in the notebook.

A simple workflow checklist

1. Define target and prediction time.
2. Remove leaky and ID columns.
3. Run setup and read the detected types.
4. Compare models with sensible metrics.
5. Pick one or two families and tune.
6. Inspect plots and explanations.
7. Check stability across seeds and folds.
8. Finalize, save and test on fresh rows.
9. Log everything.

Common mistakes

• Trusting the top of the leaderboard when the gap is small.
• Leaving ID columns or leaky columns in the data.
• Using random splits for time-ordered data.
• Tuning on the hold-out set repeatedly until it no longer measures anything.
• Ignoring class imbalance and reporting accuracy only.
• Letting a numeric code be treated as a number.
• Skipping a look at the data before calling setup.
• Treating the library as a replacement for understanding the problem.
• Deploying without testing the saved pipeline on messy inputs.
• Comparing against a foundation model with different splits or different preprocessing, which makes the comparison unfair.
• Forgetting that finalizing refits on all data, so the hold-out score no longer describes the final model.
• Running huge comparisons on a laptop with a very large table and waiting hours when a sample would have answered the question.

An example of subtle leakage

Imagine a table of loan applications with a column named "collections_status" that is only filled in after a loan goes bad. A model will score near perfectly because the column leaks the answer. The leaderboard will look wonderful. In production, that column is empty at decision time and the model collapses. The fix is a data audit, not a different algorithm.

Going deeper with PyCaret

A second worked example: regression

Regression predicts a number. The setup is almost the same as before.

import pandas as pd
from pycaret.regression import setup, compare_models, tune_model, predict_model

df = pd.read_csv("listings.csv")   # columns: area, rooms, age, district, price

setup(df, target="price", session_id=7, fold=5)
top = compare_models(sort="MAE", n_select=2)
model = tune_model(top[0], optimize="MAE", n_iter=15)
preds = predict_model(model, data=df.head(10))
print(preds[["price", "prediction_label"]])

The metric here is mean absolute error, often shortened to MAE. It is the average size of the miss, in the same unit as the target. If MAE is 12 and prices are measured in thousands, the typical miss is about 12 thousand.

A numeric walk-through of MAE and RMSE

Suppose a model predicts four prices: 100, 150, 200, 250. The true prices are 110, 140, 210, 300.

• The errors are 10, 10, 10 and 50 in size.
• MAE is the mean of 10, 10, 10 and 50, which is 20.
• Squared errors are 100, 100, 100 and 2500, with a mean of 700.
• RMSE is the square root of 700, which is about 26.5.

RMSE is larger because squaring punishes the single big miss. If big misses are costly, watch RMSE. If all misses cost the same per unit, watch MAE.

The clustering and anomaly modules

The clustering module groups rows without a target. You choose an algorithm such as k-means, call create_model, and then assign_model to label each row. This is useful for rough customer segments. Remember that clusters are a description, not a truth. Different seeds or scalings can give different groups.

The anomaly module works the same way. You pick a detector, such as an isolation-based one, and assign_model adds a flag and a score to each row. Read more on the anomaly detection page and on Isolation Forest for the idea behind one common detector.

A good habit is to review the top flagged rows by eye. If they look like data entry errors, you have a quality tool. If they look like rare but real events, you have a monitoring tool. The two uses need different actions.

The time series module

PyCaret has a separate module for forecasting. It lets you set a forecast horizon, compare several model families and plot predictions with intervals. The classic family includes ARIMA and its relatives, and the module can also use tree-based and other approaches on lagged features.

Time series validation differs from the usual kind. Folds move forward in time, so each test window comes after its training window. This is called an expanding or sliding window. It stops the model from peeking at the future.

Handling imbalanced classes

When one class is rare, a plain accuracy score is misleading. The setup step offers options to fix imbalance, such as resampling. Other choices exist as well:

• Use class weights so that rare cases count more.
• Move the decision threshold, so the model flags more cases.
• Choose a metric such as recall at a fixed precision.
• Collect more rare examples when you can.

Resampling is applied only inside the training folds, which keeps the test folds honest. If you resample before splitting by hand, you leak copies of rows into the test set and inflate the score.

Why pipelines matter

A pipeline stores the exact fitted preprocessing. Think of a recipe card stapled to the dish. Without it, someone later guesses how the dish was made. With it, a new row goes through the same steps: the same fill values, the same category codes, the same scaling. This is why the saved pipeline is more valuable than the bare model.

Reproducibility checklist

• Fix the session id.
• Record library versions.
• Save the data snapshot or its hash.
• Log metrics and settings with a tracker.
• Keep the notebook or script that produced the run.
• Store the saved pipeline next to a short readme of its limits.

Reading a leaderboard like an analyst

Do not read only the first row. Ask these questions in order:

1. How large is the gap between first and fifth place?
2. Which families are near the top? If trees dominate, the data likely has interactions or non-linear effects.
3. Is a linear model close? If yes, simpler is better.
4. What is the training time? A model that is slightly better but ten times slower may not be worth it.
5. Do scores hold up under a new seed?

Moving from prototype to production

A prototype answers "can this work?". Production asks "will it keep working?". Between them sit several tasks:

• Re-create the pipeline with pinned versions.
• Add input checks for types, ranges and missing columns.
• Add monitoring for drift in inputs and in predictions.
• Plan retraining on a schedule or on triggers.
• Document what the model should not be used for.

Tools such as MLflow help track and register models through this path.

When to stop using a low-code tool

Move to lower-level code when you need custom cross-validation, custom losses, special feature engineering, strict latency limits or very large data. There is no shame in this. A low-code tool is a ramp, not a destination.

Data quality checks before using PyCaret

A model is only as good as the table it reads. Spend ten minutes on these checks before calling setup.

Shape and types

• Count rows and columns. Very few rows per column makes any leaderboard fragile.
• List column types. Look for numbers stored as text and dates stored as text.
• Check for constant columns. They carry no signal.
• Check for columns with a unique value in every row. They are usually IDs.

Missing values

• Count gaps per column.
• Ask why they are missing. A blank can mean "not applicable", "not collected" or "error".
• If a blank itself carries meaning, add a flag column that marks it.

Duplicates and near-duplicates

Exact copies of a row in both train and test make scores too high. Remove duplicates before splitting, or split by a group key.

Target quality

• Check that the target has the values you expect.
• Check for labels that changed meaning over time.
• Check how the label was produced. A label made by a rule on the features lets a model learn the rule, not the world.

A tiny audit script

import pandas as pd

df = pd.read_csv("customers.csv")
print(df.shape)
print(df.dtypes)
print(df.isna().mean().sort_values(ascending=False).head(10))
print(df.nunique().sort_values().head(10))
print(df.duplicated().sum())

This prints the shape, the types, the share of missing values, the columns with the fewest distinct values and the number of duplicate rows. It takes seconds and prevents many surprises.

Everyday analogies for the main ideas

Analogies help when ideas feel abstract. Here are a few that match this library.

• Cross-validation is like practising an exam with several different mock papers, then averaging the marks. One mock paper might be easy by luck.
• A hold-out set is the real exam paper kept sealed until the end.
• Data leakage is seeing the answer key while studying.
• Overfitting is memorising last year's answers instead of learning the subject.
• Hyperparameter tuning is adjusting the oven temperature and time until the cake comes out right.
• An ensemble is asking a panel of doctors instead of one.
• Imputation is guessing a missing word in a sentence from the words around it.
• A pipeline is an assembly line where every item passes the same stations in the same order.

Frequently asked questions

What is PyCaret used for?

PyCaret is used to build and compare machine learning models on tables with very little code. People use it to get a quick baseline, to explore which model families suit a dataset, and to teach the steps of a standard workflow. It covers classification, regression, clustering, anomaly detection and time series forecasting.

Is PyCaret an AutoML tool?

It is often described as low-code or light AutoML. It automates preprocessing and comparison, but it does not run a large automated search over pipelines and features on its own. You remain in charge of the choices, which is the main difference from heavier hands-off services.

Does PyCaret replace scikit-learn?

No. It builds on scikit-learn and several other libraries. PyCaret gives a shorter interface, while scikit-learn gives explicit building blocks. Many teams prototype with PyCaret and then rebuild the chosen pipeline in plain scikit-learn for production.

How does compare_models decide the best model?

It trains each candidate with cross-validation and ranks them by a chosen metric, such as accuracy or area under the curve. The best row is simply the one with the highest mean score under that metric. Because small gaps can be noise, you should look at spread across folds and repeat with other seeds before trusting the order.

Can PyCaret handle missing values and categories?

Yes. The setup step can fill missing values and encode categorical columns using simple rules you can configure. These defaults are reasonable for a first pass, but you should check them against what you know about the data, since the best way to treat a gap often depends on why it is missing.

Is PyCaret good for large datasets?

It works best on small to medium tables. Because it trains many models, runtime grows quickly with size. For large data, sample first to choose a model family, then train the chosen family with a dedicated library and a proper tuning tool.

How does PyCaret relate to tabular foundation models?

It serves as a classical baseline. A tabular foundation model is pre-trained on many tables and predicts new rows in context, while PyCaret fits new models for each dataset. Comparing the two on identical splits shows whether the pre-trained model adds value for a given problem.

Can I use PyCaret for time series?

Yes, it has a time series module that supports forecasting with several model families and time-aware validation. For deeper work you may combine it with specialised forecasters such as Prophet or the classical ARIMA model.

How do I explain a PyCaret model?

You can use built-in feature importance plots and SHAP-based interpretation for global and local views. For single-row explanations you can also apply local surrogate methods. Keep in mind that explanations describe the model, not the real world, so they can reflect biases in the data.

Should I use PyCaret in production?

You can save and load its pipelines for scoring, and many people do. Still, treat the saved model like any other artifact: pin library versions, test on messy inputs, monitor drift and keep a way to retrain. Some teams prefer to export the final steps into a leaner explicit pipeline.

Glossary

• AutoML: tools that automate parts of the machine learning workflow.
• Baseline: a simple model used as a reference point for comparison.
• Class imbalance: when one outcome is much rarer than another.
• Cross-validation: a way to estimate performance using repeated splits.
• Data leakage: information in the features that would not be known at prediction time.
• Encoding: converting categories to numbers.
• Ensemble: a model that combines several models.
• Feature: a column used as input to a model.
• Hold-out set: data reserved for final checking.
• Hyperparameter: a setting fixed before training begins.
• Imputation: filling missing values.
• Leaderboard: a ranked table of model scores.
• Low-code: a style of tool that reduces the amount of code needed.
• Pipeline: a chain of steps from raw data to prediction.
• Session id: the random seed that makes a run repeatable.
• Stacking: training a model on the outputs of other models.
• Target: the column the model predicts.
• Tuning: searching for better hyperparameters.

Summary

PyCaret is a low-code Python library that turns the standard tabular machine learning workflow into a few short commands: setup, compare, tune, evaluate, finalize and save. Its strength is speed and consistency, which makes it ideal for baselines, teaching and early exploration. Its weaknesses are hidden defaults, optimistic leaderboards on small data and limited control for unusual needs.

In the wider picture of tabular modelling, PyCaret represents the classic approach of fitting models per dataset. It is a natural benchmark for newer pre-trained table models that learn from many tables and predict in context. Use it to learn fast, to set an honest baseline and to find leakage early, then move to more specialised tools when the problem demands it. For related reading, see Optuna, SHAP, TabPFN and the model research page.

Related

It belongs to Classical ML in my stack, under Foundation models and applied ML. Others in the same group: