Skip to main content

How to Log a Table in MLflow with log_table

· 6 min read
Jagdish Kumawat
Founder @ Dewiride

Some results of a run are tables: predictions next to the real values, scores per group, the importance of each feature. mlflow.log_table() saves a pandas DataFrame or a dictionary with the run as a table that the MLflow UI shows as rows and columns and can compare across runs. This guide logs a small predictions table from two models, with real output from MLflow 3.18.0.

Syntax​

Syntax
mlflow.log_table(<data>, artifact_file="<name>.json")
PartWhat it means
<data>A pandas DataFrame, or a dictionary of columns such as {"house": [...], "price": [...]}
artifact_fileThe file's name in the run, and optionally a folder: "evaluation/predictions.json". It must end in .json or .parquet
The current runThe table goes to the active run. run_id= sends it to another one

MLflow writes the table as a file in the run's artifacts and marks it as a table, which is what lets the UI show and compare it. If the run already has a table with that name, the new rows are added to it: "If the artifact_file already exists in the run, the data would be appended to the existing artifact_file."

Prerequisites​

  • An MLflow tracking server at http://127.0.0.1:8080. MLflow's tracking server guide shows how to start one. For another address, change it in the script.

Step 1: Log a Table from Two Runs​

The example is three houses with their real prices, and the prices two versions of a model predicted. Each version gets its own run, with the same table name, so the two can be compared later. Create log_table.py:

The log_table.py script in a macOS-style code window: it sets the tables-demo experiment, defines the actual prices of three houses and the predicted prices of model-v1 and model-v2, and for each model builds a DataFrame of house, actual and predicted and logs it with mlflow.log_table as predictions.json inside a run named after the model.

log_table.py
import mlflow
import pandas as pd

mlflow.set_tracking_uri("http://127.0.0.1:8080")
mlflow.set_experiment("tables-demo")

actual = [310_000, 205_000, 420_000]
models = {
"model-v1": [295_000, 230_000, 400_000],
"model-v2": [305_000, 210_000, 425_000],
}

for run_name, predicted in models.items():
table = pd.DataFrame({"house": ["A", "B", "C"], "actual": actual, "predicted": predicted})
with mlflow.start_run(run_name=run_name):
mlflow.log_table(table, artifact_file="predictions.json")
LineWhat it does
modelsEach model's predictions for houses A, B and C
pd.DataFrame({...})One row per house: its name, real price and predicted price
mlflow.log_table(table, artifact_file="predictions.json")Saves the table with the run as predictions.json
Terminal
uv run python log_table.py
Output
2026/11/19 16:26:43 INFO mlflow.tracking.fluent: Experiment with name 'tables-demo' does not exist. Creating a new experiment.
🏃 View run model-v1 at: http://127.0.0.1:8080/#/experiments/8/runs/ea0cb20b1c1f43c08099dc69835c2203
🧪 View experiment at: http://127.0.0.1:8080/#/experiments/8
🏃 View run model-v2 at: http://127.0.0.1:8080/#/experiments/8/runs/cf0ed2dc98804e6aa07eabc3a085ae79
🧪 View experiment at: http://127.0.0.1:8080/#/experiments/8

Step 2: See the Table in the UI​

Open the model-v1 run and click Artifacts, then predictions.json:

The Artifacts tab of the model-v1 run with predictions.json selected: View as table is ticked, and the preview shows a table with columns house, actual and predicted and three rows: A 310000 295000, B 205000 230000, C 420000 400000.

Because MLflow knows this file is a table, the preview has a View as table box, ticked: rows and columns, like the DataFrame you logged. Untick it to see the file itself. Its contents:

predictions.json
{"columns":["house","actual","predicted"],"data":[["A",310000,295000],["B",205000,230000],["C",420000,400000]]}

The column names come first, then one list per row. The DataFrame's row numbers aren't saved. MLflow also adds a tag to the run, mlflow.loggedArtifacts, with the value [{"path": "predictions.json", "type": "table"}]; that's how the UI knows which files are tables.

Both runs logged predictions.json, so the UI can also put them side by side: How to Compare a Logged Table Across Runs in the MLflow UI.

Common Mistakes​

MistakeWhat happensDo this instead
A file name ending in .csvValueError: Invalid artifact file path 't.csv'. Please ensure the file you are trying to log as a table has a file name with either '.json' or '.parquet' extension.End it in .json or .parquet; for a CSV file, use log_artifact
Calling log_table twice with the same name in one runThe second call adds its rows to the first: a table of 2 rows plus 1 row becomes 3 rowsLog each table once, or give each call its own name
Using different names for the same table in different runsThe runs can't be compared side by sideUse one name, such as predictions.json, in every run
Expecting the DataFrame's row labels to be savedThey're droppedTurn them into a column first with table.reset_index()

Troubleshooting​

SymptomLikely causeFix
The preview has no View as table boxThe file was logged with log_artifact, not log_tableLog it with log_table
pytest shows Pandas4Warning: For backward compatibility, 'str' dtypes are included by select_dtypesMLflow's own check for picture columns, with pandas 3Fixed: Pandas4Warning in MLflow log_table

FAQ​

Should I use .json or .parquet?​

.json is readable in the UI's preview and in any text editor. .parquet is a compact binary format that suits large tables; pandas reads it with pyarrow, which MLflow installs.

Can a table hold pictures?​

Yes. A column of images, such as PIL images, is saved as separate image files, and the table stores their paths. A column must hold only images or no images at all.

How do I read the table back in Python?​

With mlflow.load_table(), which can also stack the same table from several runs: How to Load a Logged Table from MLflow with load_table.

Conclusion​

mlflow.log_table(table, artifact_file="predictions.json") saved a three-row DataFrame with each of two runs as a JSON table: column names first, then one list per row. The UI shows it with View as table, the run gets a tag that marks it as a table, and a second call with the same name adds rows rather than replacing them.

Additional Resources​