Guide · Open source
How to use Kronos: install it and make K-line forecasts in Python
Updated · written with AI from the project's own documentation and checked against our catalogue data
Kronos is an open-source family of decoder-only foundation models pre-trained on financial K-line (candlestick) sequences made of open, high, low, close and volume data. This guide is for people comfortable with Python who want to forecast future candles on their own data. By the end you will know what to install, how to load a model from the Hugging Face Hub, and how to run single and batch forecasts.
Kronosshiyu-coder/Kronos · ★ 45.7k · MIT Install options & downloads Quick start
- 1Check prerequisites. Confirm you have Python 3.10 or newer and pip installed.
- 2Clone and install. Clone the shiyu-coder/Kronos repository and run pip install -r requirements.txt from its folder.
- 3Pick a model. Choose Kronos-mini, Kronos-small or Kronos-base from the model zoo; the README marks Kronos-large as not open-source.
- 4Load tokenizer and model. Load KronosTokenizer and Kronos from the Hugging Face Hub, then create a KronosPredictor with max_context set to 512.
- 5Prepare K-line data. Build a DataFrame with open, high, low and close columns, plus timestamps for history and for the forecast period.
- 6Run predict or predict_batch. Call predict for one series or predict_batch for several series with the same lookback and prediction length.
What Kronos does and how it works
Kronos first converts continuous candle data (OHLCV) into discrete tokens using a specialized tokenizer. A Transformer is then pre-trained on those tokens to forecast future price candles.
The project describes itself as a model for the language of financial markets rather than a trading system. The README only covers forecasting, not trading strategies or performance.
Install Kronos with pip
Kronos is installed by cloning the repository from GitHub and then installing its dependencies. You need Python 3.10 or newer and pip. The README gives this dependency command, run from the repository folder.
- Install Python 3.10+.
- Clone the shiyu-coder/Kronos repository and open its folder.
- Install dependencies from requirements.txt.
pip install -r requirements.txtChoose a Kronos model
The model zoo lists four sizes. Kronos-mini has a 2048 context length and 4.1M parameters. Kronos-small has 24.7M parameters, Kronos-base has 102.3M, and both use a 512 context length. Kronos-large has 499.2M parameters but is marked as not open-source in the README table.
All released models are loaded from the Hugging Face Hub. Each model is paired with a tokenizer, and the README pairs Kronos-mini with Kronos-Tokenizer-2k and the other sizes with Kronos-Tokenizer-base.
- Kronos-mini: context length 2048, 4.1M parameters, open-source.
- Kronos-small: context length 512, 24.7M parameters, open-source.
- Kronos-base: context length 512, 102.3M parameters, open-source.
- Kronos-large: 499.2M parameters, not listed as open-source.
Load the tokenizer and model
Import the classes from the model module, then load a tokenizer and a model from the Hugging Face Hub. The README example uses Kronos-Tokenizer-base with Kronos-small.
from model import Kronos, KronosTokenizer, KronosPredictor
tokenizer = KronosTokenizer.from_pretrained("NeoQuasar/Kronos-Tokenizer-base")
model = Kronos.from_pretrained("NeoQuasar/Kronos-small")
predictor = KronosPredictor(model, tokenizer, max_context=512)Prepare your K-line data and run a forecast
The predict method needs three inputs: df, a pandas DataFrame with at least the columns open, high, low and close (volume and amount are optional); x_timestamp, the timestamps of the history; and y_timestamp, the timestamps of the future periods to predict.
The README sets lookback to 400 and pred_len to 120, and says the max_context of Kronos-small and Kronos-base is 512. Inputs longer than that are truncated automatically, but the README recommends keeping lookback within the limit. The predict method returns a DataFrame of forecast open, high, low, close, volume and amount values indexed by y_timestamp.
The example reads a CSV file from ./data. Use your own data with the same column names, and convert the timestamps column with pd.to_datetime as shown.
- Set lookback so it does not exceed max_context.
- Use sample_count to set how many forecast paths are generated and averaged.
- T and top_p control the sampling process.
import pandas as pd
df = pd.read_csv("./data/XSHG_5min_600977.csv")
df['timestamps'] = pd.to_datetime(df['timestamps'])
lookback = 400
pred_len = 120
x_df = df.loc[:lookback-1, ['open', 'high', 'low', 'close', 'volume', 'amount']]
x_timestamp = df.loc[:lookback-1, 'timestamps']
y_timestamp = df.loc[lookback:lookback+pred_len-1, 'timestamps']
pred_df = predictor.predict(df=x_df, x_timestamp=x_timestamp, y_timestamp=y_timestamp, pred_len=pred_len, T=1.0, top_p=0.9, sample_count=1)
print(pred_df.head())Forecast multiple series with predict_batch
For several assets or time periods, predict_batch runs predictions on a list of datasets in parallel. Results come back in the same order as the inputs. The README lists requirements that every series must meet.
Batch requirements from the README: all series must have the same historical length (lookback window), and all series must have the same prediction length.
- Pass df_list, x_timestamp_list and y_timestamp_list of equal length.
- Keep the lookback window identical across series.
- Set verbose=True to see progress output.
pred_df_list = predictor.predict_batch(df_list=df_list, x_timestamp_list=x_timestamp_list, y_timestamp_list=y_timestamp_list, pred_len=pred_len, T=1.0, top_p=0.9, sample_count=1, verbose=True)What people use it for
- Forecasting the next candles for a single stock or crypto pair from historical K-line data.
- Running the same forecast settings across several assets with predict_batch.
- Fine-tuning a base model on your own market data, using the fine-tuning scripts mentioned in the README news.
- Studying how a foundation model can be applied to financial time series.
Frequently asked questions
Is Kronos free to use?
The repository is licensed under MIT, according to the project metadata. The README marks Kronos-mini, Kronos-small and Kronos-base as open-source, and Kronos-large as not open-source.
What do I need to run Kronos?
The README lists Python 3.10 or newer and pip. You also need pandas for the data examples, and the models are downloaded from the Hugging Face Hub, so you need network access to load them.
Can Kronos be used as a trading bot?
No. The README describes forecasting of K-line data and does not present trading strategies or guaranteed returns. It does not include a performance benchmark summary in the text provided, so check forecast quality yourself before relying on it.
How do I fine-tune Kronos on my own data?
The README news says fine-tuning scripts were released to adapt Kronos to your own tasks. The README excerpt here does not describe the steps, so read the repository's fine-tuning documentation for details.
What are alternatives to Kronos?
The project lists Chronos, TimesFM, Lag-Llama and Moirai as comparable projects. The README excerpt does not compare their accuracy, so test candidates on your own data.
Why does my forecast input fail?
Check that your DataFrame has open, high, low and close columns, that timestamps are converted with pd.to_datetime, and that lookback stays within max_context. For batch runs, make sure all series share the same lookback and prediction length.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Kronos suits quantitative researchers, developers and students who are comfortable with Python and want a pre-trained model for K-line forecasting or fine-tuning. It is a poor fit for anyone wanting a ready-made trading bot, a no-code tool, or guaranteed returns, and users who cannot check forecast quality themselves should look elsewhere or verify results independently.
Install options & downloads