Prophet

Overview

Prophet is an open-source forecasting model that predicts a single time series by adding together a few simple parts: a trend, one or more seasonal cycles, and the effect of holidays and special events. It was built for business series such as daily sales, web traffic or ticket volume, where the data has strong weekly and yearly patterns, a few gaps, and the occasional outlier. You give it a table with a date column and a value column, and it returns a forecast with an uncertainty band.

The main reason people choose Prophet is that it is fast to set up and easy to explain. Every part of the forecast can be plotted on its own, so an analyst can say "sales rise in December, dip on Sundays, and grow slowly over the years" and show the chart that proves it. It is not the most accurate model on every dataset. Newer deep learning and pre-trained models often win on hard benchmarks. But Prophet remains a strong, transparent baseline, and it is a good first stop for tabular time-series work before you try heavier tools such as N-BEATS, TFT, PatchTST or Chronos.

What it is

Prophet is a decomposable time-series model. Decomposable means the forecast is built from separate pieces that you can look at one by one. The core equation is short:

y(t) = g(t) + s(t) + h(t) + e(t)

Here g(t) is the trend, s(t) is the repeating seasonal pattern, h(t) is the effect of holidays or events, and e(t) is the leftover noise that the model does not explain.

Think of a shop owner reading a sales ledger. She notices three things. Sales grow a little every year. Saturdays are busy and Mondays are quiet. Sales jump before certain public holidays. Prophet writes down exactly those three habits as math, then uses them to guess the future.

The three main parts

• Trend. A curve that captures the long-term direction. It can be a piecewise straight line or a saturating logistic curve that levels off at a cap.
• Seasonality. Smooth repeating cycles, such as weekly and yearly patterns, modeled with Fourier series (sums of sine and cosine waves).
• Holidays and events. A list of dates that you provide, each with an optional window before and after, so the model can learn a bump or dip for each one.

What it is built on

Prophet is a regression model, not a neural network. It is fitted with a Bayesian approach. By default it finds the most likely parameter values (a maximum a posteriori estimate), and it can optionally draw full posterior samples. The fitting engine behind it is a probabilistic programming language called Stan. Users usually never touch Stan directly. They call a small Python or R interface with fit and predict.

Who uses it

• Analysts who need a forecast this afternoon and have no time to tune a network.
• Product and operations teams that must explain a forecast to non-technical readers.
• Data scientists who want a quick baseline to beat.
• Teams that forecast thousands of separate series on a schedule and need a model that rarely crashes.

Where it came from

Prophet came out of the practical needs of a data science team at a large social media company. The team had many forecasting requests and few forecasting experts. Classic tools such as ARIMA are powerful but need careful, per-series tuning and assume fairly regular data. The team wanted something that analysts with domain knowledge could steer without a statistics degree.

The model was released as open source in 2017 and described in a paper titled "Forecasting at Scale" by Sean Taylor and Benjamin Letham. The paper's central idea was to treat forecasting as a curve-fitting problem rather than a pure time-series dependence problem. This is a different mindset from ARIMA. In ARIMA, today's value depends on yesterday's values. In Prophet, the value depends on the calendar: the date, the day of week, the day of year, and whether there is a holiday.

Why the curve-fitting view matters

Curve fitting has some handy side effects:

• Observations do not need to be evenly spaced. Missing days are simply missing rows.
• Outliers can be removed by setting values to missing, with no special treatment.
• Changes in trend can be placed at chosen dates, and the user can inspect them.
• Domain knowledge, such as a known product launch or promotion, can be added as an event.

Later developments

Over the years the project added extra regressors (other columns that help predict the target), multiplicative seasonality, logistic growth with floors, and uncertainty options. The community also built wrappers and ports. The original package went through periods of slower maintenance, and some users moved to newer alternatives. Even so, the design ideas from Prophet have influenced many later forecasting libraries, and its decomposition plots are copied widely.

How it works

This section walks through the model one step at a time. Each step has an everyday analogy.

Step 1: Prepare the data

Prophet expects two columns. The date column is named ds and the value column is named y. Each row is one observation. There is no need for a regular grid, but most users have daily or hourly data.

Analogy: a diary. Each line says "on this date, this much happened". The model reads the diary and looks for habits.

Step 2: Fit the trend

The trend is the slow movement of the series. By default Prophet uses a piecewise linear trend. Imagine drawing the trend with a ruler, but you are allowed to bend the ruler at certain points. Those bend points are called changepoints.

• Prophet places a set of candidate changepoints across the early part of the history (by default across the first 80 percent).
• At each candidate, the slope is allowed to change by a small amount.
• A sparse prior (a gentle penalty) pushes most of those changes toward zero. So only changepoints that the data really supports end up with a visible bend.

The strength of that penalty is a setting called the changepoint prior scale. A larger value lets the trend bend easily, which risks overfitting. A smaller value keeps the trend stiff, which risks underfitting.

Analogy: a road with many possible turn signs. At most signs, the car goes straight. It turns only when the road clearly turns.

Step 3: Choose linear, logistic or flat growth

• Linear growth is right for series that keep rising or falling.
• Logistic growth is right for saturating series. You give a capacity (a ceiling), and the trend curves toward it. A market with a fixed number of potential customers is a classic example.
• Flat growth is right for series with no trend at all.

Step 4: Fit the seasonality

Seasonality is a pattern that repeats on a fixed period. Prophet models it with a Fourier series. A Fourier series builds any smooth repeating curve out of simple waves.

Analogy: a music equalizer. A complex sound is a mix of pure tones. A few low tones give a smooth shape. More tones add detail but also add wiggle.

• Weekly seasonality uses a period of 7 days and a small number of terms.
• Yearly seasonality uses a period of about 365.25 days and a larger number of terms (ten by default).
• You can add custom seasonalities, such as a monthly cycle or an hourly cycle within a day.

The Fourier order controls the detail. A higher order fits sharper patterns and can overfit. A lower order is smoother.

Step 5: Choose additive or multiplicative seasonality

In additive mode, the seasonal effect is a fixed amount added to the trend. Saturday adds 200 units, whatever the level.

In multiplicative mode, the seasonal effect scales with the trend. Saturday adds 10 percent. When a business doubles in size, the seasonal swings double too. If the swings grow as the series grows, multiplicative mode is the better choice.

Step 6: Add holidays and events

You provide a table of event names and dates. You can add a lower window and an upper window, so that the days before and after count too. For example, the days around a big sale may all behave differently.

Each event gets its own coefficient. The model learns whether the event raises or lowers the value, and by how much. If the same event is repeated in many years, the estimate becomes more stable.

Step 7: Add extra regressors

If you know other columns in advance, such as planned ad spend, a price, or a weather forecast, you can add them as regressors. These columns must be available for the future dates too. Otherwise you would have to forecast them separately.

Step 8: Estimate the parameters

Prophet writes all of the above as one probabilistic model and then solves for the best parameters. In the default mode it uses an optimizer and returns point estimates. This is quick, usually seconds per series. In full Bayesian mode it samples the posterior, which is slower but gives uncertainty for seasonal and holiday effects.

Step 9: Forecast and uncertainty

To forecast, you build a future table of dates and call predict. The output contains the forecast (yhat), a lower and upper bound, and every component (trend, weekly, yearly, holidays).

The uncertainty band comes mostly from simulating future trend changes. The model assumes that future trend changes will be about as frequent and as large as past ones, and it draws random changepoints on that basis. It also adds the noise level estimated from the fit. This is why the band widens with the horizon.

Step 10: Check the forecast with cross-validation

Prophet includes a time-series cross-validation helper. It cuts the history at several cutoff dates, trains on the data before each cutoff, and forecasts a fixed horizon ahead. It then computes errors by horizon. This is the honest way to learn how good the model is.

Key concepts and terms

A worked example

This example forecasts a daily series with weekly and yearly patterns, a custom holiday and one extra regressor. All names are placeholders.

Setting up the data

import pandas as pd
from prophet import Prophet

df = pd.read_csv("daily_orders.csv")        # columns: date, orders, promo
df = df.rename(columns={"date": "ds", "orders": "y"})
df["ds"] = pd.to_datetime(df["ds"])

# remove a known data outage by setting values to missing
df.loc[(df.ds >= "2024-03-10") & (df.ds <= "2024-03-12"), "y"] = None

Setting bad values to None is the Prophet way to handle outages. The model simply ignores those rows.

Defining events

events = pd.DataFrame({
    "holiday": "big_sale",
    "ds": pd.to_datetime(["2023-11-24", "2024-11-29"]),
    "lower_window": -1,
    "upper_window": 2,
})

The window covers one day before and two days after each sale date.

Fitting the model

m = Prophet(
    growth="linear",
    seasonality_mode="multiplicative",
    changepoint_prior_scale=0.05,
    yearly_seasonality=10,
    weekly_seasonality=3,
    holidays=events,
)
m.add_regressor("promo")
m.fit(df)

The choices here are reasonable defaults. Multiplicative mode is used because the seasonal swings grow with the level of orders.

Forecasting

future = m.make_future_dataframe(periods=60)      # 60 days ahead
future = future.merge(df[["ds", "promo"]], on="ds", how="left")
future["promo"] = future["promo"].fillna(0)       # planned: no promo
forecast = m.predict(future)
print(forecast[["ds", "yhat", "yhat_lower", "yhat_upper"]].tail())

The regressor must have a value for each future date. Here we assume no promotion.

Looking at the parts

fig1 = m.plot(forecast)
fig2 = m.plot_components(forecast)

The components plot shows trend, the weekly shape, the yearly shape, the sale effect and the promo effect on separate panels. This is where Prophet shines. If the weekly panel shows a Sunday dip of 30 percent, a manager can check that against what they know.

Measuring accuracy

from prophet.diagnostics import cross_validation, performance_metrics

cv = cross_validation(m, initial="540 days", period="30 days", horizon="60 days")
metrics = performance_metrics(cv)
print(metrics[["horizon", "mape", "rmse"]].head())

This trains on the first 540 days, forecasts 60 days, then slides forward 30 days and repeats. The result is an error curve by horizon.

A small numeric walk-through

Suppose, for a single date, the model has:

• trend value of 1,000 orders,
• a weekly multiplier of +0.10 (Saturday),
• a yearly multiplier of -0.05 (a slow season),
• a sale multiplier of +0.20.

In multiplicative mode, the forecast is 1000 x (1 + 0.10 - 0.05 + 0.20) = 1250. In additive mode with the same numbers expressed as fixed amounts, you would simply add them to 1,000. The difference is whether the effects scale with the level.

Tuning loop

A sensible tuning loop is small:

1. Fit with defaults and cross-validate.
2. If the trend is too stiff, raise changepoint_prior_scale.
3. If the trend chases noise, lower it.
4. If holidays behave oddly, change windows.
5. Re-run cross-validation and compare errors by horizon.

Stop when gains are small. Over-tuning on a short history is a common trap.

Strengths and limitations

Strengths

• Easy to start. Two columns and a few lines of code give a working forecast.
• Interpretable. Each part of the forecast can be plotted and discussed.
• Handles gaps and outliers. Missing rows do not break the fit.
• Handles calendar effects well. Weekly, yearly and holiday patterns are first-class.
• Lets experts steer. You can set changepoints, caps, events and priors.
• Scales to many series. Fitting one series takes seconds, so thousands can run in a batch job.
• Gives uncertainty bands. Useful for planning and risk.

Limitations

• Mostly a single-series model. It does not learn shared patterns across thousands of related series. Each series is fitted on its own.
• Weak short-term dynamics. Because it is a curve fit on the calendar, it does not use recent autocorrelation well. If last hour's value strongly predicts the next hour, ARIMA-style or neural models can do better.
• Needs enough history. For yearly seasonality, you want at least two full years.
• Trend extrapolation can be risky. A recent upward bend may be extended too far into the future.
• Limited covariate handling. Regressors are linear. Complex interactions are not learned.
• Not the top performer on hard benchmarks. Independent studies have often found well-tuned statistical and neural methods more accurate on many datasets.
• Uncertainty is approximate. The band rests on assumptions about future trend changes and Gaussian noise.
• Sensitive to the settings. The default changepoint behavior may not suit every series.

When it fits best

Prophet works best for daily or weekly business data, with at least a year or two of history, clear calendar patterns and moderate noise. It is less suited to high-frequency sensor data, very short series, or series driven by fast dynamics.

How it compares with alternatives

A common practical pattern is to use Prophet as a baseline. If a more complex model cannot beat it by a clear margin in cross-validation, the simple model stays.

Role in tabular foundation models

Prophet is not a foundation model. It does not pre-train on many tables and it has no in-context learning. But it touches the same world in several useful ways.

The row and column view

A tabular foundation model reads a table: rows are records, columns are features, and a target column is predicted. A Prophet input is also a table with a date column and a value column. The difference is that Prophet treats each row as a point on a time axis, while a tabular foundation model treats rows as exchangeable examples. When time matters, a table has to be turned from one form into the other, and Prophet is one of the cleanest ways to extract the time structure.

Feature generation for tabular models

The components Prophet learns can become features for a table model.

• The fitted trend value at each date is a smooth, de-noised feature.
• The weekly and yearly seasonal values are cyclic features that need no manual sine and cosine encoding.
• Holiday effect columns are ready-made event features.
• The residual y - yhat is a clean target for a second-stage model such as XGBoost or LightGBM, which then learns what Prophet could not.

Stacking Prophet with a tree model is a classic hybrid: the calendar part is handled by a transparent model, and the messy tabular part by a flexible one.

Mixed types and missing values

Real tables mix numbers, categories, dates and text, and they have gaps. Prophet handles dates and numbers, and it handles missing target values by ignoring them. It does not deal with categorical columns directly. If a table has a category such as "region", the usual approach is to fit one Prophet model per category or to use the category as an event or a regressor. A pre-trained tabular model such as TabPFN or TabICL takes mixed types in one pass, without a separate model per group. That is a real convenience for wide tables, though these models are not designed around long time axes in the way Prophet is.

No column names

Foundation-style models are often tested with column names hidden, to check that they use the structure of the data rather than the words in the headers. Prophet depends on the fixed names ds and y only as an interface convention. Internally it does not use any language meaning of column names. It is, in that sense, name-blind: rename the columns and the math is the same.

Pre-training on synthetic or real tables

Prophet has no pre-training. Every series is fitted from scratch with its own parameters. Pre-trained time-series models such as Chronos instead learn general patterns from many series, some of them synthetic, and then apply them zero-shot. The two ideas can be combined. A simple approach is to use Prophet's decomposition to remove trend and seasonality, then give the residual to a pre-trained model. Another is to use Prophet-style generated series as part of a synthetic data generation recipe, since trend plus seasonality plus noise is an easy way to produce realistic fake series.

In-context learning and continual learning

In-context learning means a model sees examples in its prompt and adapts without weight updates. Prophet does not do this. Its closest cousin is simply refitting: each time new data arrives, you fit again, which takes seconds. This is cheap continual updating, but it forgets nothing and learns nothing across series. A foundation model that learns across tables can carry knowledge from one dataset to the next. See few-shot learning and transfer learning for the general ideas.

Imputation

Prophet can fill gaps in a time series. You fit the model on the observed rows and then predict the missing dates. This is a seasonal-aware fill that beats a simple mean or forward fill when patterns are strong. For general tables with missing cells in many columns, a model that learns column relationships, such as those discussed under imputation networks, is a better fit. Prophet's imputation covers one column over time only.

Anomaly detection

Because Prophet gives an uncertainty interval, it is a simple anomaly detector. A point outside the interval is flagged as unusual. This is the basis of many alerting systems for traffic and sales. The method works best when the series has stable patterns. For richer detection across many columns, see anomaly detection and predictive maintenance.

Sector and semantic classification

Classification by sector or meaning (for example, deciding whether a column is a price, a date or an ID) is a different task from forecasting. Prophet does not do it. However, a forecasting pipeline over a large table often needs such typing first, to know which columns are time axes and which are targets. A tabular foundation model that infers the role of columns from their values can supply that step, after which Prophet-style models can be applied to the time-based ones. For more on how these models are built, see /model/architecture, /model/research and /model/benchmarks.

A fair summary of its role

Prophet is best seen as a transparent specialist and a feature factory. A tabular foundation model is a generalist that learns from many tables. They serve different jobs, and they combine well.

Practical guidance and best practices

Data preparation

• Use a consistent time zone and drop the time zone before fitting if the library requires naive timestamps.
• Aggregate to the frequency you want to forecast. Daily data should be daily, not a mix of daily and hourly rows.
• Remove or blank out known outages and one-off glitches rather than leaving them in.
• Keep at least two seasonal cycles of history for the main seasonality.
• Check for a constant series or very few non-zero values. Intermittent demand is a poor fit.

Model settings

• Start with defaults, then adjust one setting at a time.
• Use multiplicative seasonality when swings grow with the level.
• Use logistic growth with a cap when there is a real ceiling.
• Add events for known dates that matter, and give them windows.
• Add regressors only when you will know their future values.
• Change changepoint_range if you expect recent bends to matter.

Validation

• Always cross-validate with a horizon equal to the one you will use in production.
• Compare against simple baselines: last value, seasonal naive (same day last week or last year), and a moving average.
• Report error by horizon, not just one average number.
• Use an error measure that fits the business. MAPE breaks near zero, so prefer MAE, RMSE or a scaled error for series with small values.

Production habits

• Refit on a schedule (daily or weekly) and store the forecasts with the date they were made.
• Track forecast error over time and alert when it drifts.
• Keep a manual override path for known events that the model could not know about.
• Keep the model code, settings and event lists in version control.
• For thousands of series, run fits in parallel and set sensible time limits.

Explaining results

• Show the components plot to stakeholders.
• Explain the uncertainty band as "a likely range", not a guarantee.
• Point out the changepoints that the model found and tie them to business events.

Scaling to many series

Many teams need forecasts for thousands of products or stores. A few habits keep this manageable.

• Group series by behavior. Fast sellers, slow sellers and new items need different settings.
• Use a shared default configuration, then override only for series that fail validation.
• Run fits in parallel, one series per task, and cap run time.
• Save each fit's error so you can see which series need attention.
• For new items with no history, borrow the shape from similar items or use a pre-trained model.

Handling special situations

• Structural breaks. If a business changed sharply (a new market, a price change), consider fitting only on data after the break, or add a regressor that marks the change.
• Long outages. Blank them out. If the outage was a real drop in demand, keep it and mark it as an event instead.
• Intermittent demand. Series with many zeros do not suit a smooth curve. Use methods built for sparse counts.
• Strong day-of-week by season interactions. Use conditional seasonalities, which switch a weekly pattern on or off depending on a condition such as in-season versus off-season.
• Hourly data. Add a daily seasonality and consider a custom hourly cycle for weekdays and weekends.

Choosing an error measure

A short checklist before shipping

1. Does the forecast beat seasonal naive in cross-validation?
2. Are errors stable across cutoffs, or do they jump?
3. Do the component plots match what domain experts expect?
4. Is the future regressor data really available at forecast time?
5. Is there a plan for refits and for monitoring drift?

Common mistakes

1. Skipping cross-validation. A good-looking in-sample fit says little. Always test on held-out future periods.
2. Fitting on too little history. With under a year of data, yearly seasonality is guesswork.
3. Ignoring the outlier problem. Leaving an outage in the data teaches the model a false dip.
4. Using a regressor with unknown future values. If you must forecast the regressor first, errors compound.
5. Over-flexible trend. A very high changepoint prior scale makes the model follow noise and then extrapolate it.
6. Under-flexible trend. A very low value misses real shifts and gives biased forecasts.
7. Wrong seasonality mode. Using additive mode when swings grow with level gives poor fits at high and low levels.
8. Too many holidays. Dozens of weak events can overfit. Keep those that matter.
9. Forecasting too far ahead. A horizon much longer than the history is mostly trend extrapolation.
10. Trusting the interval blindly. Real errors can be larger than the band, especially after a structural change.
11. Using MAPE on small values. It blows up near zero and misleads.
12. Treating Prophet as the end of the road. A quick check against a tree model on lag features or a pre-trained model may show an easy win.

Frequently asked questions

What is Prophet used for?

Prophet is used to forecast a single time series with clear trend, repeating seasonal patterns and holiday effects. Typical examples are daily sales, website visits, call volumes and energy demand at the daily level. It is popular because it is quick to set up, tolerant of missing data, and easy to explain with component plots.

Is Prophet a machine learning model or a statistical model?

It is best described as a statistical regression model fitted with Bayesian methods. It is not a neural network and it does not use deep learning. It is still often grouped with machine learning tools because it learns parameters from data and is used for prediction in data science workflows.

How much data does Prophet need?

For daily data with yearly seasonality, you want at least two years so the model sees each season more than once. For weekly patterns alone, a few months can be enough. With very little history, the model may still run, but the seasonal estimates will be unreliable.

Can Prophet handle missing values?

Yes, in the target column. Rows with a missing y are simply skipped during fitting, and you can predict the dates they cover. Missing values in extra regressors are not allowed, so those must be filled before fitting.

How is Prophet different from ARIMA?

ARIMA models each value as a function of its own recent past and past errors. Prophet models each value as a function of the calendar: trend, seasonal cycles and events. ARIMA tends to do better on short-term, smooth series. Prophet tends to do better when calendar effects and holidays dominate and when data has gaps.

Does Prophet work for multivariate forecasting?

Not in the usual sense. It forecasts one target at a time. You can add other columns as regressors, but each must be known in the future, and the effect is linear. Models such as TFT or PatchTST are built for richer multivariate settings.

Is Prophet still worth using now that foundation models exist?

Yes, as a baseline and as an explainable tool. Pre-trained models can forecast new series without training and often score well, but they are harder to inspect. A simple Prophet fit gives a quick reference point, and its decomposition is easy to share with non-technical readers.

How do I choose between additive and multiplicative seasonality?

Look at a plot. If the seasonal swings stay about the same size as the series grows, use additive. If the swings grow in proportion to the level, use multiplicative. When unsure, try both in cross-validation and keep the one with lower error.

Can Prophet detect anomalies?

It can serve as a simple detector. Fit the model, compare actual values to the uncertainty interval, and flag points that fall outside. This works well for stable series. For noisy or changing series, combine it with a more careful detection method.

Why does my Prophet forecast look too smooth?

The model is designed to capture trend and seasonality, not short-term wiggles. If your series has strong day-to-day dependence, Prophet will smooth it away. Adding lag-based features in a tree model, or using a neural model, can capture those short-term moves.

Glossary

• Additive model. A model where the parts are added together.
• Multiplicative model. A model where the parts are multiplied, so effects scale with the level.
• Bayesian estimation. A way of fitting that combines data with prior beliefs about parameters.
• Changepoint. A date where the trend is allowed to change slope.
• Cross-validation. Testing a model on several held-out periods in time order.
• Exogenous regressor. An outside variable that helps predict the target.
• Fourier series. A sum of sine and cosine waves that builds a repeating curve.
• Forecast horizon. How many steps ahead the forecast reaches.
• Logistic growth. A trend shape that rises and levels off at a cap.
• MAE. Mean absolute error, the average size of the mistakes.
• MAPE. Mean absolute percentage error, which is unstable near zero.
• Seasonality. A pattern that repeats at a fixed interval.
• Seasonal naive. A baseline that predicts the value from the same point in the last cycle.
• Stan. A probabilistic programming language used to fit the model.
• Trend. The long-term direction of the series.
• Uncertainty interval. The range in which future values are likely to fall.
• Zero-shot. Predicting on new data with no training on it.

Summary

Prophet is an additive, decomposable forecasting model that splits a series into trend, seasonality and holiday effects. It is easy to use, tolerant of messy business data, and very good at explaining itself through component plots. Its weaknesses are limited short-term dynamics, a single-series focus and a ceiling on accuracy compared with well-tuned deep or pre-trained models.

In the wider tabular modeling world, Prophet is a transparent specialist and a useful feature generator rather than a foundation model. It does not pre-train, learn in context or work across many tables. But its trend, seasonal and residual outputs feed well into tree models and foundation models, and it remains a fair baseline against N-BEATS, TFT, PatchTST and Chronos. Use it first, validate it honestly, and move to something heavier only when the numbers say you should.

Related

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