> ## Documentation Index
> Fetch the complete documentation index at: https://docs.priorlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> TabPFN-3 and later versions support up to 1,000,000 rows, subject to feature count and checkpoint/API limits.
> For large datasets, use per-estimator subsampling, e.g. inference_config={"SUBSAMPLE_SAMPLES": 100_000}, in TabPFNClassifier or TabPFNRegressor from tabpfn or tabpfn_client.
> Pass raw pandas DataFrames to fit and predict. Categorical strings/categories, raw text, and missing feature values are handled automatically; no manual integer/one-hot encoding, imputation, scaling, or outlier removal is needed.

# Fine-tuning base class

> Abstract base class for fine-tuning TabPFN models.

<Info>
  Looking for usage documentation? Check out [Fine tuning](/capabilities/fine-tuning).
</Info>

<div className="python-reference-heading">
  <h2 id="finetunedtabpfnbase">
    `FinetunedTabPFNBase`
  </h2>

  <a className="python-reference-source" href="https://github.com/PriorLabs/TabPFN/blob/c70b6ef0488858d32244c52222abfc0c5be207d6/src/tabpfn/finetuning/finetuned_base.py#L350" aria-label="View source for FinetunedTabPFNBase"><span aria-hidden="true">\</></span> View source <span aria-hidden="true">↗</span></a>
</div>

Abstract base class for fine-tuning TabPFN models.

This class encapsulates the shared fine-tuning logic, allowing you to
fine-tune TabPFN on a specific dataset using the familiar .fit() and
.predict() API.

```python theme={null}
FinetunedTabPFNBase(
    *,
    device: str = "cuda",
    epochs: int = 30,
    time_limit: int | None = None,
    learning_rate: float = 1e-05,
    weight_decay: float = 0.01,
    validation_split_ratio: float | None = 0.1,
    n_finetune_ctx_plus_query_samples: int = 50000,
    finetune_ctx_query_split_ratio: float = 0.2,
    n_inference_subsample_samples: int | None = None,
    random_state: int = 0,
    early_stopping: bool = True,
    early_stopping_patience: int = 8,
    validation_frequency: int = 1,
    min_delta: float = 0.0001,
    grad_clip_value: float | None = 1.0,
    use_lr_scheduler: bool = True,
    lr_warmup_only: bool = False,
    n_estimators_finetune: int = 2,
    n_estimators_validation: int = 2,
    n_estimators_final_inference: int = 2,
    use_activation_checkpointing: bool = True,
    shard_estimators_across_gpus: bool = False,
    save_checkpoint_interval: int | None = 10,
    use_fixed_preprocessing_seed: bool = True,
    experiment_logger: FinetuningLogger | None = None,
    model_version: ModelVersion | None = None,
)
```

**Parameters**

<div className="python-reference-table">
  | Parameter | Type | Default | Description |
  | - | - | - | - |
  | <span id="finetunedtabpfnbase--device" /><code className="python-reference-parameter">device</code> | <code className="python-reference-type">str</code> | `"cuda"` | The device to run the model on. Defaults to "cuda". |
  | <span id="finetunedtabpfnbase--epochs" /><code className="python-reference-parameter">epochs</code> | <code className="python-reference-type">int</code> | `30` | The total number of passes through the fine-tuning data. Defaults to `30`. |
  | <span id="finetunedtabpfnbase--time-limit" /><code className="python-reference-parameter">time\_<wbr />limit</code> | <code className="python-reference-type">int \| None</code> | `None` | Time limit in seconds for fine-tuning. If `None`, no time limit is applied. Defaults to `None`. |
  | <span id="finetunedtabpfnbase--learning-rate" /><code className="python-reference-parameter">learning\_<wbr />rate</code> | <code className="python-reference-type">float</code> | `1e-05` | The learning rate for the AdamW optimizer. A small value is crucial for stable fine-tuning. Defaults to 1e-5. |
  | <span id="finetunedtabpfnbase--weight-decay" /><code className="python-reference-parameter">weight\_<wbr />decay</code> | <code className="python-reference-type">float</code> | `0.01` | The weight decay for the AdamW optimizer. Defaults to `0.01`. |
  | <span id="finetunedtabpfnbase--validation-split-ratio" /><code className="python-reference-parameter">validation\_<wbr />split\_<wbr />ratio</code> | <code className="python-reference-type">float \| None</code> | `0.1` | Fraction of the original training data reserved as a validation set for early stopping and monitoring. Set to 0 or `None` to disable validation: all data is then used for fine-tuning, per-epoch evaluation is skipped, and early stopping is disabled. Ignored when explicit validation data is passed to [`fit`](/api-reference/python/tabpfn/finetuning/base#finetunedtabpfnbase-fit). Defaults to `0.1`. |
  | <span id="finetunedtabpfnbase--n-finetune-ctx-plus-query-samples" /><code className="python-reference-parameter">n\_<wbr />finetune\_<wbr />ctx\_<wbr />plus\_<wbr />query\_<wbr />samples</code> | <code className="python-reference-type">int</code> | `50000` | The total number of samples per meta-dataset during fine-tuning (context plus query) before applying the `finetune_ctx_query_split_ratio`. Defaults to 50\_000. |
  | <span id="finetunedtabpfnbase--finetune-ctx-query-split-ratio" /><code className="python-reference-parameter">finetune\_<wbr />ctx\_<wbr />query\_<wbr />split\_<wbr />ratio</code> | <code className="python-reference-type">float</code> | `0.2` | The proportion of each fine-tuning meta-dataset to use as query samples for calculating the loss. The remainder is used as context. Defaults to `0.2`. |
  | <span id="finetunedtabpfnbase--n-inference-subsample-samples" /><code className="python-reference-parameter">n\_<wbr />inference\_<wbr />subsample\_<wbr />samples</code> | <code className="python-reference-type">int \| None</code> | `None` | The total number of subsampled training samples per estimator during validation and final inference. If `None`, no subsampling is applied and the full training set is used as context. Defaults to `None`. |
  | <span id="finetunedtabpfnbase--random-state" /><code className="python-reference-parameter">random\_<wbr />state</code> | <code className="python-reference-type">int</code> | `0` | Seed for reproducibility of data splitting and model initialization. Defaults to `0`. |
  | <span id="finetunedtabpfnbase--early-stopping" /><code className="python-reference-parameter">early\_<wbr />stopping</code> | <code className="python-reference-type">bool</code> | `True` | Whether to use early stopping based on validation performance. When enabled, the best-performing weights are restored at the end of training and a best checkpoint is saved alongside the interval checkpoints. When disabled, training runs all epochs and the last-epoch weights are kept (no best checkpoint is saved). Defaults to `True`. |
  | <span id="finetunedtabpfnbase--early-stopping-patience" /><code className="python-reference-parameter">early\_<wbr />stopping\_<wbr />patience</code> | <code className="python-reference-type">int</code> | `8` | Number of validation checks to wait for improvement before early stopping. Defaults to `8`. |
  | <span id="finetunedtabpfnbase--validation-frequency" /><code className="python-reference-parameter">validation\_<wbr />frequency</code> | <code className="python-reference-type">int</code> | `1` | Number of epochs between validation checks. A value of 1 (default) validates after every epoch, preserving the existing behavior. The initial evaluation of the unfine-tuned model still runs whenever validation data is available. With a value greater than 1, `early_stopping_patience` counts validation checks rather than epochs. Must be a positive integer. |
  | <span id="finetunedtabpfnbase--min-delta" /><code className="python-reference-parameter">min\_<wbr />delta</code> | <code className="python-reference-type">float</code> | `0.0001` | Minimum change in metric to be considered as an improvement. Defaults to 1e-4. |
  | <span id="finetunedtabpfnbase--grad-clip-value" /><code className="python-reference-parameter">grad\_<wbr />clip\_<wbr />value</code> | <code className="python-reference-type">float \| None</code> | `1.0` | Maximum norm for gradient clipping. If `None`, gradient clipping is disabled. Gradient clipping helps stabilize training by preventing exploding gradients. Defaults to `1.0`. |
  | <span id="finetunedtabpfnbase--use-lr-scheduler" /><code className="python-reference-parameter">use\_<wbr />lr\_<wbr />scheduler</code> | <code className="python-reference-type">bool</code> | `True` | Whether to use a learning rate scheduler (linear warmup with optional cosine decay) during fine-tuning. Defaults to `True`. |
  | <span id="finetunedtabpfnbase--lr-warmup-only" /><code className="python-reference-parameter">lr\_<wbr />warmup\_<wbr />only</code> | <code className="python-reference-type">bool</code> | `False` | If `True`, only performs linear warmup to the base learning rate and then keeps it constant. If `False`, applies cosine decay after warmup. Defaults to `False`. |
  | <span id="finetunedtabpfnbase--n-estimators-finetune" /><code className="python-reference-parameter">n\_<wbr />estimators\_<wbr />finetune</code> | <code className="python-reference-type">int</code> | `2` | If set, overrides `n_estimators` of the underlying estimator only during fine-tuning to control the number of estimators (ensemble size) used in the training loop. If `None`, the value from `kwargs` or the estimator default is used. Defaults to `2`. |
  | <span id="finetunedtabpfnbase--n-estimators-validation" /><code className="python-reference-parameter">n\_<wbr />estimators\_<wbr />validation</code> | <code className="python-reference-type">int</code> | `2` | If set, overrides `n_estimators` only for validation-time evaluation during fine-tuning (early-stopping / monitoring). If `None`, the value from `kwargs` or the estimator default is used. Defaults to `2`. |
  | <span id="finetunedtabpfnbase--n-estimators-final-inference" /><code className="python-reference-parameter">n\_<wbr />estimators\_<wbr />final\_<wbr />inference</code> | <code className="python-reference-type">int</code> | `2` | If set, overrides `n_estimators` only for the final fitted inference model that is used after fine-tuning. If `None`, the value from `kwargs` or the estimator default is used. Defaults to `2`. |
  | <span id="finetunedtabpfnbase--use-activation-checkpointing" /><code className="python-reference-parameter">use\_<wbr />activation\_<wbr />checkpointing</code> | <code className="python-reference-type">bool</code> | `True` | Whether to use activation checkpointing to reduce memory usage. Defaults to `True`. |
  | <span id="finetunedtabpfnbase--shard-estimators-across-gpus" /><code className="python-reference-parameter">shard\_<wbr />estimators\_<wbr />across\_<wbr />gpus</code> | <code className="python-reference-type">bool</code> | `False` | When `True` under DDP, every rank processes the same data chunk but only a shard of the fine-tuning estimators. DDP then averages gradients across estimator shards. This reduces per-rank activation memory instead of only distributing data chunks. Defaults to `False`. |
  | <span id="finetunedtabpfnbase--save-checkpoint-interval" /><code className="python-reference-parameter">save\_<wbr />checkpoint\_<wbr />interval</code> | <code className="python-reference-type">int \| None</code> | `10` | Number of epochs between checkpoint saves. This only has an effect if `output_dir` is provided during the [`fit()`](/api-reference/python/tabpfn/finetuning/base#finetunedtabpfnbase-fit) call. If `None`, no intermediate checkpoints are saved. The best model checkpoint is always saved regardless of this setting. Defaults to `10`. |
  | <span id="finetunedtabpfnbase--use-fixed-preprocessing-seed" /><code className="python-reference-parameter">use\_<wbr />fixed\_<wbr />preprocessing\_<wbr />seed</code> | <code className="python-reference-type">bool</code> | `True` | Whether to use a fixed preprocessing seed. If `True`, the preprocessing will always use the same random seed throughout data batches. This is helpful in most cases because, e.g., the column order will stay the same across batches. If `False`, the preprocessing will use a different random seed for each batch. |
  | <span id="finetunedtabpfnbase--experiment-logger" /><code className="python-reference-parameter">experiment\_<wbr />logger</code> | <code className="python-reference-type"><a href="/api-reference/python/tabpfn/finetuning/logging#finetuninglogger">Finetuning<wbr />Logger</a> \| None</code> | `None` | An optional logger implementing the [`FinetuningLogger`](/api-reference/python/tabpfn/finetuning/logging#finetuninglogger) protocol (e.g., [`WandbLogger`](/api-reference/python/tabpfn/finetuning/logging#wandblogger)) for experiment tracking. If `None`, a no-op [`NullLogger`](/api-reference/python/tabpfn/finetuning/logging#nulllogger) is used. Defaults to `None`. |
  | <span id="finetunedtabpfnbase--model-version" /><code className="python-reference-parameter">model\_<wbr />version</code> | <code className="python-reference-type"><a href="/api-reference/python/tabpfn/model-versions#modelversion">Model<wbr />Version</a> \| None</code> | `None` | Which TabPFN model version to fine-tune. If `None` (default), uses the package default version (`settings.tabpfn.model_version`) — the same version a default [`TabPFNClassifier`](/api-reference/python/tabpfn/classifier/configuration#constructor)/[`TabPFNRegressor`](/api-reference/python/tabpfn/regressor/configuration#constructor) loads — so fine-tuning tracks the current default model rather than a hardcoded one. Defaults to `None`. |
</div>

***

<div className="python-reference-heading">
  <h2 id="finetunedtabpfnbase-finetune-model-version">
    `FinetunedTabPFNBase.finetune_model_version`
  </h2>

  <a className="python-reference-source" href="https://github.com/PriorLabs/TabPFN/blob/c70b6ef0488858d32244c52222abfc0c5be207d6/src/tabpfn/finetuning/finetuned_base.py#L526" aria-label="View source for FinetunedTabPFNBase.finetune_model_version"><span aria-hidden="true">\</></span> View source <span aria-hidden="true">↗</span></a>
</div>

Model version to fine-tune; falls back to the package default version.

When `model_version` is not set explicitly, this resolves to
`settings.tabpfn.model_version` (the same default a plain
[`TabPFNClassifier`](/api-reference/python/tabpfn/classifier/configuration#constructor)/[`TabPFNRegressor`](/api-reference/python/tabpfn/regressor/configuration#constructor) uses), so fine-tuning tracks the
current default model version instead of a hardcoded one.

**Returns**

<div className="python-reference-table python-reference-returns">
  | Type | Description |
  | - | - |
  | <code className="python-reference-type"><a href="/api-reference/python/tabpfn/model-versions#modelversion">Model<wbr />Version</a></code> | — |
</div>

***

<div className="python-reference-heading">
  <h2 id="finetunedtabpfnbase-predict">
    `FinetunedTabPFNBase.predict`
  </h2>

  <a className="python-reference-source" href="https://github.com/PriorLabs/TabPFN/blob/c70b6ef0488858d32244c52222abfc0c5be207d6/src/tabpfn/finetuning/finetuned_base.py#L685" aria-label="View source for FinetunedTabPFNBase.predict"><span aria-hidden="true">\</></span> View source <span aria-hidden="true">↗</span></a>
</div>

Predict target values for `X`.

```python theme={null}
FinetunedTabPFNBase.predict(
    X: np.ndarray,
) -> np.ndarray
```

**Parameters**

<div className="python-reference-table">
  | Parameter | Type | Default | Description |
  | - | - | - | - |
  | <span id="finetunedtabpfnbase-predict--x" /><code className="python-reference-parameter">X</code> | <code className="python-reference-type"><a href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html">np.ndarray</a></code> | Required | — |
</div>

**Returns**

<div className="python-reference-table python-reference-returns">
  | Type | Description |
  | - | - |
  | <code className="python-reference-type"><a href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html">np.ndarray</a></code> | — |
</div>

***

<div className="python-reference-heading">
  <h2 id="finetunedtabpfnbase-fit">
    `FinetunedTabPFNBase.fit`
  </h2>

  <a className="python-reference-source" href="https://github.com/PriorLabs/TabPFN/blob/c70b6ef0488858d32244c52222abfc0c5be207d6/src/tabpfn/finetuning/finetuned_base.py#L729" aria-label="View source for FinetunedTabPFNBase.fit"><span aria-hidden="true">\</></span> View source <span aria-hidden="true">↗</span></a>
</div>

Fine-tune the TabPFN model on the provided training data.

```python theme={null}
FinetunedTabPFNBase.fit(
    X: XType,
    y: YType,
    X_val: XType | None = None,
    y_val: YType | None = None,
    output_dir: Path | None = None,
) -> FinetunedTabPFNBase
```

<Accordion title="Type aliases">
  ```python theme={null}
  XType = Any
  YType = Any
  ```
</Accordion>

**Parameters**

<div className="python-reference-table">
  | Parameter | Type | Default | Description |
  | - | - | - | - |
  | <span id="finetunedtabpfnbase-fit--x" /><code className="python-reference-parameter">X</code> | <code className="python-reference-type"><a href="https://github.com/PriorLabs/TabPFN/blob/c70b6ef0488858d32244c52222abfc0c5be207d6/src/tabpfn/constants.py#L25">X<wbr />Type</a></code> | Required | The training input samples of shape (n\_samples, n\_features). |
  | <span id="finetunedtabpfnbase-fit--y" /><code className="python-reference-parameter">y</code> | <code className="python-reference-type"><a href="https://github.com/PriorLabs/TabPFN/blob/c70b6ef0488858d32244c52222abfc0c5be207d6/src/tabpfn/constants.py#L26">Y<wbr />Type</a></code> | Required | The target values of shape (n\_samples,). |
  | <span id="finetunedtabpfnbase-fit--x-val" /><code className="python-reference-parameter">X\_<wbr />val</code> | <code className="python-reference-type"><a href="https://github.com/PriorLabs/TabPFN/blob/c70b6ef0488858d32244c52222abfc0c5be207d6/src/tabpfn/constants.py#L25">X<wbr />Type</a> \| None</code> | `None` | Optional validation input samples. |
  | <span id="finetunedtabpfnbase-fit--y-val" /><code className="python-reference-parameter">y\_<wbr />val</code> | <code className="python-reference-type"><a href="https://github.com/PriorLabs/TabPFN/blob/c70b6ef0488858d32244c52222abfc0c5be207d6/src/tabpfn/constants.py#L26">Y<wbr />Type</a> \| None</code> | `None` | Optional validation target values. |
  | <span id="finetunedtabpfnbase-fit--output-dir" /><code className="python-reference-parameter">output\_<wbr />dir</code> | <code className="python-reference-type"><a href="https://docs.python.org/3/library/pathlib.html#pathlib.Path">Path</a> \| None</code> | `None` | Directory path for saving checkpoints. If `None`, no checkpointing is performed and progress will be lost if training is interrupted. |
</div>

**Returns**

<div className="python-reference-table python-reference-returns">
  | Type | Description |
  | - | - |
  | <code className="python-reference-type"><a href="/api-reference/python/tabpfn/finetuning/base#finetunedtabpfnbase">Finetuned<wbr />Tab<wbr />PFN<wbr />Base</a></code> | The fitted instance itself. |
</div>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.