Nixtla's nixtla SDK: TimeGPT Forecasting Without Training Your Own Model

What the nixtla package actually is, and who it is for

The README describes TimeGPT as a generative pretrained transformer for time series, trained on over 100B data points, and the nixtla package as the Python SDK that talks to it. That distinction matters more than most quickstarts admit. The repository you clone is a client. The model runs elsewhere, behind an API, and you reach it with an API key obtained from Nixtla's free trial page.

So the audience is narrow and specific. You are an analyst or engineer with a table of timestamps and values, you want a forecast this afternoon, and you do not want to train, tune or host anything. The README's pitch is that retail, electricity, finance and IoT series all work with a few lines of code. The flip side is that every one of those lines is a network call, and your series leaves your machine to produce it.

If the phrase "foundation model" makes you expect a downloadable checkpoint, correct that expectation early. Nothing in the repository layout suggests weights ship with the package. The top-level entries are notebooks, tests, docs, a Makefile and the Python source under nixtla/. There is no model directory.

How the SDK talks to TimeGPT: client, dataframe, response

The data flow is short enough to hold in your head. You construct a NixtlaClient with an API key. You hand it a pandas dataframe with at least a time column and a target column. The client serialises that frame, posts it to the Nixtla endpoint, and returns a dataframe of forecasts or anomaly flags that you can plot with the same client object.

Configuration lives on the client, not in a config file. The README's own examples pass api_key directly to the constructor. Because the constructor also accepts other parameters, the practical pattern is to read the key from the environment and pass it in, rather than committing a literal string.

The dependency list in pyproject.toml tells you what the client is built on: httpx with zstd compression for transport, orjson for fast serialisation, pandas capped below 3.0.0, pyarrow for columnar interchange, pydantic for request and response models, tenacity for retries and tqdm for progress. That is a client library's dependency set, not a modelling stack. There is no torch, no lightning, no GPU runtime in the base dependencies.

One consequence worth stating plainly: the client is thin, so almost all of the behaviour you care about (accuracy, latency, rate limits, interval calibration) is determined by the remote service. Upgrading the package changes the client contract, not the model.

Installing nixtla and running a first forecast

The README pins a minimum version in the install line, so use it rather than a bare install:

pip install nixtla>=0.7.0

If you prefer to keep the API key out of your source, install python-dotenv from the dev extras and load a .env file before constructing the client. The README itself does not show that pattern; it passes the key inline.

A first forecast needs a dataframe with a time column and a target column. The README's electricity example reads a CSV straight from a URL, so you can reproduce it without any local data:

import pandas as pd
from nixtla import NixtlaClient

nixtla_client = NixtlaClient(api_key='YOUR API KEY HERE')

df = pd.read_csv(
    'https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/electricity-short.csv'
)

fcst_df = nixtla_client.forecast(df, h=24, level=[80, 90])
nixtla_client.plot(df, fcst_df, level=[80, 90])

You should get back a dataframe with one row per forecast horizon step per series, plus lower and upper columns for each requested interval level. The plot call draws history and forecast on the same axes.

Anomaly detection uses the same client with a different method and explicit column names:

anomalies_df = nixtla_client.detect_anomalies(
    df, time_col='timestamp', target_col='value', freq='D'
)
nixtla_client.plot(df, anomalies_df, time_col='timestamp', target_col='value')

Note that forecast in the README example is called without time_col or target_col, while detect_anomalies passes them. If your column names differ from the defaults, pass them in both calls; the README does not spell out what those defaults are.

The Snowflake path, for teams that cannot move data

The README documents a second deployment route aimed squarely at the data-residency objection: run TimeGPT inside your Snowflake environment. The install is an extra:

pip install nixtla[snowflake]
python -m nixtla.scripts.snowflake_install_nixtla

According to the README, the script creates stored procedures and UDTFs, walks you through external access integrations, configures your API key, and deploys the forecasting components to a database and schema you choose. The Makefile exposes the same entry point as a target:

make deploy-snowflake

Read the claim carefully. The README says this enables forecasting on your Snowflake data "without moving it outside your infrastructure". That is a statement about where the data sits, not about where computation happens. The script still configures an API key and an external access integration, which means the warehouse reaches out to Nixtla's service. If your compliance requirement is that no series crosses your network boundary at all, this route does not obviously satisfy it, and the README does not document an offline mode. Ask Nixtla directly what leaves the warehouse before you treat this as a data-residency solution.

Where the hosted-model design bites

The first limitation is the obvious one and it is not a footnote. Every forecast is an API call to a service you do not operate. Outages, rate limits, per-call quotas and regional endpoints are all outside your control, and the README does not document rollback, offline fallback or a local replica. If your pipeline must produce a forecast at 03:00 regardless of a third party's status, you need your own fallback model behind the same interface.

The second limitation is reproducibility. A hosted model can be updated server-side without a version bump in the SDK you installed. Your pyproject.toml pin constrains the client, not the weights. If you need to explain why last quarter's forecast looked the way it did, you are relying on the vendor's records, not yours.

The third is that the package is labelled Beta in its own classifiers, and the current version string is 0.9.0.dev1. Development releases in the version number are a signal about API stability, not about model quality, but they are a signal.

The fourth is the licence split. The SDK is Apache 2.0, and the repository ships a THIRD_PARTY_LICENSES.md generated by a pip-licenses target in the Makefile. The hosted service is governed by separate terms that the README does not reproduce. An Apache 2.0 client does not make the endpoint free or unrestricted.

nixtla vs darts and Prophet: different answers to the same question

The comparison people search for is nixtla against darts or Prophet, and the difference is architectural rather than a matter of accuracy. darts and Prophet are libraries you install and run locally. You fit a model on your own machine, you own the artefact, and nothing leaves your process. Nixtla's SDK does the opposite: it keeps the modelling remote and the local footprint tiny.

That inversion is the whole argument. If you have a small number of series and a modest machine, a local library gives you reproducibility and no per-call cost. If you have many series, irregular timestamps, or no appetite for tuning, the hosted route removes the modelling work from your plate and the README's irregular-timestamp support is aimed at exactly that case.

Prophet's design assumes you can express trend and seasonality explicitly and want to inspect the components. TimeGPT's design assumes you would rather not. Neither is wrong; they fail in different places. Prophet fails when your series are too numerous to fit one at a time. The nixtla SDK fails when the network is down or the data cannot travel.

Within Nixtla's own family, the boundaries are clearer. statsforecast, mlforecast, neuralforecast and hierarchicalforecast are the local libraries; the nixtla package is the client for the hosted model. Several of them appear in the pyproject.toml dev extras, which is why notebooks in this repository can compare the two approaches side by side.

Maintenance, upgrades and what the repository tells you

The last push to the default branch was on 2026-09-09, and the most recent releases are v0.9.0.dev1 on 2026-09-03 and v0.9.0.dev0 on 2026-09-01, following v0.8.0 on 2026-07-21. The repository is not archived. Two dev releases inside a week, ahead of a 0.9.0 line, is the pattern of a project mid-cycle rather than one coasting.

For upgrade cost, the practical risk is dependency drift, not API churn. The base dependencies include pandas capped below 3.0.0 and pyarrow capped below 24.0.0, so a major pandas release will force a coordinated bump. The distributed extra pins pandas below 2.3.0 and ray at or below 2.56.1, which means the distributed path and the default path can disagree about pandas versions in the same environment. If you plan to use the fugue, dask, ray or spark extras, resolve them in a separate environment.

Contributors have a documented path: uv sync with all groups and extras, pre-commit install, ruff format, and a lint target that runs pre-commit over nixtla/*. The Makefile's licenses target regenerates THIRD_PARTY_LICENSES.md from pip-licenses output, which is the file to hand to whoever reviews dependencies. On licensing, note that the repository's GitHub metadata reports NOASSERTION while pyproject.toml declares Apache Software License 2.0 and the README badge says Apache 2.0. Treat the pyproject declaration as the operative one, and get your own legal read on the hosted service terms, which are separate from the code licence.

Editorial conclusion

Adopt the nixtla SDK if you want zero-shot forecasts from a hosted model and can send your series to Nixtla's API, and if your stack already speaks pandas or Polars. Do not adopt it if your data cannot leave your network, if you need a self-contained open source model you can retrain, or if you want a free unlimited endpoint. Before committing, verify three things: that your API key works against the endpoint your region expects, that the returned intervals at level=[80, 90] are wide enough for your decisions, and that your licence review covers both the Apache 2.0 SDK and the hosted service terms. The repository's own THIRD_PARTY_LICENSES.md is the file to read first.

Frequently asked questions

Official sources

1. Issues
2. Nixtla/nixtla on GitHub
3. Project website
4. README
5. Releases