AutoGluon: A Complete Guide to AWS's AutoML Library for Real-World Machine Learning
AutoGluon is an open-source AutoML library developed by AWS that enables you to build high-quality machine learning models with just a few lines of code. Whether you are working with tabular data, text, images, or time series, AutoGluon automates the heavy lifting of model selection, hyperparameter tuning, and ensemble construction so you can focus on solving real problems rather than tweaking configurations.
In this tutorial, we will walk through everything you need to know to get started with AutoGluon and apply it to practical scenarios. We will cover its three core predictors (TabularPredictor, MultiModalPredictor, and TimeSeriesPredictor), build real projects, and discuss best practices for production deployments.
Why AutoGluon?
Before diving into the code, it is worth understanding what makes AutoGluon stand out among AutoML frameworks like H2O AutoML, TPOT, and Auto-sklearn.
Key advantages of AutoGluon:- State-of-the-art accuracy out of the box. AutoGluon consistently wins or places near the top in AutoML benchmarks. Its multi-layer stacking and ensemble approach often outperforms hand-tuned models.
- Minimal code required. You can train a competitive model in three lines of code: load data, fit, predict.
- Multi-modal support. A single library handles tabular data, text, images, and time series without needing separate frameworks.
- Production-ready. Models can be saved, loaded, and deployed easily. AutoGluon handles missing values, feature engineering, and data preprocessing automatically.
- Flexible time budgets. You can set a training time limit and AutoGluon will optimize how it allocates that budget across different models and ensembles.
Installation
AutoGluon is available on PyPI and can be installed with pip. The library is modular, so you can install only the components you need.
Full Installation
To install AutoGluon with all features (tabular, multimodal, and time series):
pip install autogluon
This is the simplest approach and is recommended if you have sufficient disk space and want access to all predictors.
Modular Installation
If you only need specific functionality, you can install individual modules to keep your environment lightweight:
# Tabular data only (classification, regression)
pip install autogluon.tabular
Multimodal (text, image, tabular combinations)
pip install autogluon.multimodal
Time series forecasting
pip install autogluon.timeseries
Environment Recommendations
AutoGluon works best with the following setup:
# Create a fresh virtual environment
python -m venv autogluon-env
source autogluon-env/bin/activate # Linux/Mac
autogluon-env\Scripts\activate # Windows
Upgrade pip first
pip install --upgrade pip
Install AutoGluon
pip install autogluon
Verify the installation
python -c "import autogluon; print(autogluon.version)"
System requirements:
- Python 3.9, 3.10, or 3.11 (Python 3.12+ support may vary by version)
- At least 8 GB of RAM (16 GB or more recommended for larger datasets)
- GPU is optional but strongly recommended for multimodal tasks involving text or images
Basic Usage: TabularPredictor
The TabularPredictor is AutoGluon's flagship feature and what most users start with. It handles structured/tabular data for both classification and regression tasks.
Example 1: Predicting House Prices
Let us build a regression model that predicts house prices using a real dataset. We will use the Ames Housing dataset, which contains 79 features describing residential homes in Ames, Iowa.
from autogluon.tabular import TabularPredictor, TabularDataset
import pandas as pd
Load the dataset
You can use any CSV file; here we use a sample housing dataset
traindata = TabularDataset("https://autogluon.s3.amazonaws.com/datasets/AmesHousingTrain.csv")
testdata = TabularDataset("https://autogluon.s3.amazonaws.com/datasets/AmesHousingTest.csv")
Inspect the data
print(f"Training samples: {len(traindata)}")
print(f"Test samples: {len(testdata)}")
print(f"Features: {list(traindata.columns)}")
print(traindata.head())
Now, training a model is remarkably simple:
# Define the target column
target = "SalePrice"
Train the predictor
predictor = TabularPredictor(
label=target,
evalmetric="rootmeansquarederror",
path="models/housepricepredictor"
)
predictor.fit(
traindata=traindata,
timelimit=300, # 5 minutes training budget
presets="bestquality"
)
The presets parameter controls the trade-off between speed and accuracy:
| Preset | Description | Use Case |
|--------|-------------|----------|
| bestquality | Maximum accuracy, slower training | Final production models |
| highquality | Good accuracy, moderate training time | Most practical scenarios |
| goodquality | Balanced speed and accuracy | Quick experimentation |
| mediumquality | Faster training, reasonable accuracy | Rapid prototyping |
After training, you can make predictions and evaluate the model:
# Make predictions on test data
predictions = predictor.predict(testdata)
print("Sample predictions:")
print(predictions.head(10))
Evaluate performance
performance = predictor.evaluate(testdata)
print(f"\nModel performance: {performance}")
View the leaderboard of all trained models
leaderboard = predictor.leaderboard(testdata)
print("\nModel Leaderboard:")
print(leaderboard)
Example 2: Customer Churn Classification
Classification works the same way. Let us predict whether a customer will churn:
from autogluon.tabular import TabularPredictor, TabularDataset
Load a churn prediction dataset
traindata = TabularDataset("churntrain.csv")
testdata = TabularDataset("churntest.csv")
Train a classifier
predictor = TabularPredictor(
label="Churn",
evalmetric="f1",
path="models/churnpredictor"
)
predictor.fit(
traindata=traindata,
timelimit=120,
presets="highquality"
)
Get predictions
predictions = predictor.predict(testdata)
Get prediction probabilities
probabilities = predictor.predictproba(testdata)
print(probabilities.head())
Feature importance analysis
importance = predictor.featureimportance(testdata)
print("\nFeature Importance:")
print(importance)
AutoGluon automatically detects that this is a binary classification problem based on the target column values and selects appropriate models and metrics.
Understanding What AutoGluon Does Under the Hood
When you call predictor.fit(), AutoGluon performs the following steps automatically:
MultiModalPredictor: Text, Image, and Beyond
The MultiModalPredictor extends AutoGluon's capabilities to handle text, images, and combinations of different data types. This is particularly powerful when your dataset contains a mix of structured data and unstructured content.
Example 3: Text Classification (Sentiment Analysis)
Let us build a sentiment classifier for product reviews:
from autogluon.multimodal import MultiModalPredictor
import pandas as pd
Create a sample dataset
traindata = pd.DataFrame({
"review": [
"This product is amazing! Best purchase I ever made.",
"Terrible quality. Broke after one week of use.",
"Decent product for the price. Nothing special.",
"Absolutely love it! Exceeded all my expectations.",
"Worst experience ever. Do not buy this.",
"Good value for money. Works as described.",
"The build quality is outstanding. Highly recommended.",
"Complete waste of money. Very disappointed.",
"It is okay. Does what it says but nothing more.",
"Fantastic! Five stars from me without hesitation.",
],
"sentiment": [
"positive", "negative", "neutral", "positive", "negative",
"positive", "positive", "negative", "neutral", "positive",
]
})
In practice, you would have a much larger dataset
This is just for demonstration purposes
Train the multimodal predictor
predictor = MultiModalPredictor(
label="sentiment",
evalmetric="accuracy",
path="models/sentimentpredictor"
)
predictor.fit(
traindata=traindata,
timelimit=120
)
Predict on new reviews
newreviews = pd.DataFrame({
"review": [
"I really enjoy using this product every day.",
"Not worth the money at all.",
"It works fine, nothing extraordinary."
]
})
predictions = predictor.predict(newreviews)
probabilities = predictor.predictproba(newreviews)
for review, pred, prob in zip(newreviews["review"], predictions, probabilities.values):
print(f"Review: {review}")
print(f"Prediction: {pred}")
print(f"Confidence: {max(prob):.2%}")
print()
Example 4: Multimodal Prediction (Text + Tabular)
One of AutoGluon's unique strengths is combining different data types in a single model. Here is an example that combines product descriptions (text) with numerical features:
from autogluon.multimodal import MultiModalPredictor
import pandas as pd
Dataset with both text and numerical features
traindata = pd.DataFrame({
"productdescription": [
"Premium wireless headphones with noise cancellation",
"Budget earbuds with basic sound quality",
"Professional studio monitor headphones",
"Compact Bluetooth speaker with deep bass",
"High-end audiophile headphone amplifier",
],
"brandrating": [4.5, 2.8, 4.2, 3.9, 4.7],
"numreviews": [1250, 340, 890, 2100, 450],
"weightgrams": [280, 45, 350, 520, 680],
"pricecategory": ["high", "low", "high", "medium", "premium"]
})
predictor = MultiModalPredictor(
label="pricecategory",
path="models/pricepredictor"
)
predictor.fit(
traindata=traindata,
timelimit=60
)
The MultiModalPredictor uses transformer-based models (such as BERT or DeBERTa) for text features and combines them with traditional models for numerical and categorical features through a fusion architecture.
Supported Data Types in MultiModalPredictor
| Data Type | Example | Model Used |
|-----------|---------|------------|
| Text | Product reviews, descriptions | Transformer (BERT, DeBERTa, etc.) |
| Image | Product photos, medical scans | Vision Transformer, ResNet |
| Tabular (Numeric) | Price, ratings, counts | Fusion MLP |
| Tabular (Categorical) | Category, color, size | Embedding layers |
| Combination | All of the above mixed | Late/early fusion architecture |
TimeSeriesPredictor: Forecasting the Future
AutoGluon's TimeSeriesPredictor brings the same ease of use to time series forecasting. It supports multiple forecasting models and automatically handles seasonality, trends, and complex patterns.
Example 5: Sales Forecasting
Let us forecast monthly sales for the next 12 months:
from autogluon.timeseries import TimeSeriesPredictor, TimeSeriesDataFrame
import pandas as pd
import numpy as np
Generate sample sales data for multiple stores
np.random.seed(42)
dates = pd.daterange("2022-01-01", periods=36, freq="M")
datarecords = []
for storeid in range(1, 4):
base = 1000 storeid
for i, date in enumerate(dates):
seasonal = 200 np.sin(2 np.pi i / 12)
trend = 10 i
noise = np.random.normal(0, 50)
sales = base + seasonal + trend + noise
datarecords.append({
"itemid": f"store{storeid}",
"timestamp": date,
"target": max(0, sales)
})
traindf = pd.DataFrame(datarecords)
Convert to TimeSeriesDataFrame
traindata = TimeSeriesDataFrame.fromdataframe(
traindf,
idcolumn="itemid",
timestampcolumn="timestamp"
)
print(f"Time series data shape: {traindata.shape}")
print(f"Number of unique items: {traindata.numitems}")
print(traindata.head(10))
Train the forecaster
predictor = TimeSeriesPredictor(
predictionlength=12, # Forecast 12 months ahead
evalmetric="MASE", # Mean Absolute Scaled Error
path="models/salesforecaster"
)
predictor.fit(
traindata=traindata,
timelimit=300,
presets="highquality"
)
Generate forecasts
forecasts = predictor.predict(traindata)
print("\nForecasts:")
print(forecasts.head(20))
Example 6: Energy Demand Forecasting with Covariates
For more advanced scenarios, you can include exogenous features (covariates) in your time series model:
from autogluon.timeseries import TimeSeriesPredictor, TimeSeriesDataFrame
import pandas as pd
import numpy as np
Generate hourly energy demand data with weather covariates
np.random.seed(123)
hours = pd.daterange("2024-01-01", periods=720, freq="H") # 30 days
records = []
for hour in hours:
temperature = 20 + 10 np.sin(2 np.pi hour.hour / 24) + np.random.normal(0, 2)
isweekend = 1 if hour.dayofweek >= 5 else 0
basedemand = 500 - 5 abs(temperature - 22) # comfort zone effect
demand = basedemand + (100 if not isweekend else -50) + np.random.normal(0, 20)
records.append({
"itemid": "grid1",
"timestamp": hour,
"target": max(0, demand),
"temperature": temperature,
"isweekend": isweekend,
})
df = pd.DataFrame(records)
tsdata = TimeSeriesDataFrame.fromdataframe(
df,
idcolumn="itemid",
timestampcolumn="timestamp"
)
Split into train and test
traindata = tsdata.slicebytimestep(None, -48) # All except last 48 hours
testdata = tsdata # Full data for evaluation
predictor = TimeSeriesPredictor(
predictionlength=48, # Forecast 48 hours ahead
evalmetric="MAPE",
path="models/energyforecaster",
knowncovariatesnames=["isweekend"], # Known future values
)
predictor.fit(
traindata=traindata,
timelimit=180,
presets="highquality"
)
For prediction, you need to provide known covariates for the forecast horizon
knowncovariates = testdata[["isweekend"]].slicebytimestep(-48, None)
forecasts = predictor.predict(traindata, knowncovariates=knowncovariates)
evaluation = predictor.evaluate(testdata)
print(f"Forecast evaluation: {evaluation}")
View model leaderboard
leaderboard = predictor.leaderboard(testdata)
print("\nModel Leaderboard:")
print(leaderboard)
Models Used by TimeSeriesPredictor
AutoGluon's TimeSeriesPredictor trains and ensembles several forecasting models:
- Statistical models: ETS, ARIMA, Theta, Naive, SeasonalNaive
- Machine learning models: LightGBM-based tabular models that use lag features
- Deep learning models: DeepAR, Temporal Fusion Transformer (TFT), PatchTST
- Ensemble: Weighted combination of the above models
Advanced Usage
Custom Hyperparameters
You can customize which models AutoGluon trains and their hyperparameters:
from autogluon.tabular import TabularPredictor
Define custom hyperparameters
customhyperparameters = {
"GBM": [
{"numboostround": 500, "learningrate": 0.05},
{"numboostround": 1000, "learningrate": 0.01},
],
"CAT": {}, # Use default CatBoost settings
"XGB": {}, # Use default XGBoost settings
"NNTORCH": {
"numepochs": 50,
"learningrate": 1e-3,
"dropoutprob": 0.1,
},
}
predictor = TabularPredictor(label="target", path="models/custommodel")
predictor.fit(
traindata=traindata,
hyperparameters=customhyperparameters,
timelimit=600,
numstacklevels=2, # Number of stacking levels
numbagfolds=10, # Number of bagging folds
)
Model Persistence: Save and Load
AutoGluon models are saved automatically during training. You can load them later for inference:
from autogluon.tabular import TabularPredictor
Models are saved to the path specified during training
Load a previously trained predictor
predictor = TabularPredictor.load("models/housepricepredictor")
Use it for predictions
newdata = TabularDataset("newhouses.csv")
predictions = predictor.predict(newdata)
Feature Engineering and Data Exploration
AutoGluon provides tools to understand your model and data:
# Feature importance
importance = predictor.featureimportance(testdata, numshufflesets=5)
print("Top 10 most important features:")
print(importance.head(10))
Model information
modelinfo = predictor.info()
print(f"\nBest model: {predictor.modelbest}")
print(f"All models trained: {predictor.modelnames()}")
Detailed leaderboard with extra info
leaderboard = predictor.leaderboard(testdata, extrainfo=True)
print(leaderboard[["model", "scoreval", "predtimeval", "fittime"]])
Distillation for Faster Inference
If you need faster predictions in production, you can distill the ensemble into a single model:
# Train with bestquality first
predictor = TabularPredictor(label="target", path="models/full
model")
predictor.fit(traindata, presets="bestquality", timelimit=600)
Distill into a smaller, faster model
distilledpredictor = predictor.distill(
timelimit=120,
augmentmethod="spunge", # Data augmentation for distillation
)
The distilled model is much faster while retaining most accuracy
print("Original inference time vs distilled:")
originalspeed = predictor.leaderboard(testdata)[["model", "predtimeval"]]
distilledspeed = distilledpredictor.leaderboard(testdata)[["model", "predtimeval"]]
print(originalspeed.head())
print(distilledspeed.head())
Handling Large Datasets
For large datasets that do not fit in memory, AutoGluon provides several strategies:
predictor = TabularPredictor(label="target", path="models/largedata")
Use lighter presets for speed
predictor.fit(
traindata=traindata,
presets="mediumquality",
timelimit=3600,
# Reduce memory usage
hyperparameters={
"GBM": {},
"CAT": {},
},
# Limit stacking to reduce memory
numstacklevels=0,
numbagfolds=5,
# Sample if needed
samplesize=100000, # Use a subset for training
)
Best Practices
1. Start Simple, Then Iterate
Begin with default settings and a short time limit to establish a baseline:
# Quick baseline (2 minutes)
predictor = TabularPredictor(label="target")
predictor.fit(traindata, timelimit=120, presets="mediumquality")
baselinescore = predictor.evaluate(testdata)
Then invest more time if needed
predictorv2 = TabularPredictor(label="target", path="models/v2")
predictorv2.fit(traindata, timelimit=3600, presets="bestquality")
improvedscore = predictorv2.evaluate(testdata)
2. Choose the Right Evaluation Metric
Select a metric that aligns with your business objective:
# For regression
predictor = TabularPredictor(label="price", evalmetric="meanabsoluteerror")
Other options: rootmeansquarederror, r2, medianabsoluteerror
For binary classification
predictor = TabularPredictor(label="churn", evalmetric="f1")
Other options: accuracy, rocauc, precision, recall, logloss
For multi-class classification
predictor = TabularPredictor(label="category", evalmetric="accuracy")
Other options: f1macro, f1weighted, logloss
3. Handle Imbalanced Datasets
For classification tasks with imbalanced classes:
# Option 1: Use appropriate metrics
predictor = TabularPredictor(
label="fraud",
evalmetric="f1", # Better than accuracy for imbalanced data
)
Option 2: Use sample weights
traindata["sampleweight"] = traindata["fraud"].map({0: 1.0, 1: 10.0})
predictor.fit(
traindata=traindata,
sampleweight="sampleweight",
timelimit=300,
)
4. Proper Train-Test Splitting
Always validate your model on held-out data:
from sklearn.modelselection import traintestsplit
Split your data before training
train
data, testdata = traintestsplit(
full
data,
testsize=0.2,
randomstate=42,
stratify=fulldata["target"] # For classification
)
predictor = TabularPredictor(label="target")
predictor.fit(traindata, timelimit=300)
Evaluate on truly unseen data
finalperformance = predictor.evaluate(testdata)
print(f"Test performance: {finalperformance}")
5. Production Deployment Tips
When deploying AutoGluon models to production:
# 1. Save the model with a versioned path
import datetime
version = datetime.datetime.now().strftime("%Y%m%d%H%M%S")
modelpath = f"models/production/houseprice{version}"
predictor = TabularPredictor(label="target", path=modelpath)
predictor.fit(traindata, presets="bestquality", timelimit=3600)
2. Clone only the best model for smaller deployment size
predictor.clonefordeployment(path=f"{modelpath}deployed")
3. Load and predict in production
productionpredictor = TabularPredictor.load(f"{modelpath}deployed")
predictions = productionpredictor.predict(incomingdata)
4. Monitor model performance over time
Log predictions and compare with actual outcomes
6. Memory and Compute Optimization
# Reduce memory usage by excluding heavy models
predictor.fit(
traindata,
excludedmodeltypes=["KNN", "NNTORCH"], # Exclude memory-heavy models
timelimit=300,
)
Use fewer bag folds to save memory
predictor.fit(
traindata,
numbagfolds=3, # Default is 8 for bestquality
numstacklevels=0, # Disable stacking
timelimit=300,
)
Persist models in memory for faster repeated predictions
predictor.persistmodels("best") # Keep best model in memory
7. Logging and Monitoring
Keep track of your experiments:
import logging
Set AutoGluon logging verbosity
0 = no output, 1 = minimal, 2 = standard, 3 = detailed, 4 = debug
predictor = TabularPredictor(
label="target",
path="models/experiment01",
verbosity=2
)
After training, export results
leaderboard = predictor.leaderboard(testdata, extrainfo=True)
leaderboard.tocsv("experiment01results.csv", index=False)
Log the training summary
results = predictor.fitsummary()
Common Pitfalls to Avoid
fit() method or use it for any form of model selection outside of AutoGluon's internal validation.Conclusion
AutoGluon is one of the most practical AutoML libraries available today. It removes the complexity of model selection, hyperparameter tuning, and ensembling while delivering competitive or state-of-the-art results across tabular, text, image, and time series tasks.
Here is a summary of what we covered:
- TabularPredictor handles structured data for classification and regression with automatic model selection and multi-layer stacking.
- MultiModalPredictor processes text, images, and mixed data types using transformer-based fusion architectures.
- TimeSeriesPredictor provides forecasting capabilities with statistical, machine learning, and deep learning models combined into ensembles.
The library is particularly well-suited for teams that want strong ML performance without dedicating weeks to manual model development. Start with presets="mediumquality" for quick experiments, then scale up to "best_quality" when you are ready for production.
For further learning, explore the official AutoGluon documentation at https://auto.gluon.ai and the GitHub repository at https://github.com/autogluon/autogluon.
Written by Ruby Abdullah for rubythalib.ai*