> ## 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-tuned regressor

> A scikit-learn compatible wrapper for fine-tuning the TabPFNRegressor.

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

<div className="python-reference-heading">
  <h2 id="finetunedtabpfnregressor">
    `FinetunedTabPFNRegressor`
  </h2>

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

A scikit-learn compatible wrapper for fine-tuning the [`TabPFNRegressor`](/api-reference/python/tabpfn/regressor/configuration#constructor).

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

```python theme={null}
FinetunedTabPFNRegressor(
    *,
    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 = 8,
    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,
    extra_regressor_kwargs: dict[str, Any] | None = None,
    ce_loss_weight: float = 0.0,
    crps_loss_weight: float = 1.0,
    crls_loss_weight: float = 0.0,
    mse_loss_weight: float = 1.0,
    mse_loss_clip: float | None = None,
    mae_loss_weight: float = 0.0,
    mae_loss_clip: float | None = None,
    eval_metric: Literal["mse"] | None = None,
    model_version: ModelVersion | None = None,
)
```

**Parameters**

<div className="python-reference-table">
  | Parameter | Type | Default | Description |
  | - | - | - | - |
  | <span id="finetunedtabpfnregressor--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="finetunedtabpfnregressor--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="finetunedtabpfnregressor--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="finetunedtabpfnregressor--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="finetunedtabpfnregressor--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="finetunedtabpfnregressor--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/regressor#finetunedtabpfnregressor-fit). Defaults to `0.1`. |
  | <span id="finetunedtabpfnregressor--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="finetunedtabpfnregressor--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="finetunedtabpfnregressor--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="finetunedtabpfnregressor--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="finetunedtabpfnregressor--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. Defaults to `True`. |
  | <span id="finetunedtabpfnregressor--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="finetunedtabpfnregressor--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. The initial evaluation of the unfine-tuned model still runs whenever validation data is available. Must be a positive integer. |
  | <span id="finetunedtabpfnregressor--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="finetunedtabpfnregressor--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="finetunedtabpfnregressor--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="finetunedtabpfnregressor--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="finetunedtabpfnregressor--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="finetunedtabpfnregressor--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="finetunedtabpfnregressor--n-estimators-final-inference" /><code className="python-reference-parameter">n\_<wbr />estimators\_<wbr />final\_<wbr />inference</code> | <code className="python-reference-type">int</code> | `8` | 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 `8`. |
  | <span id="finetunedtabpfnregressor--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="finetunedtabpfnregressor--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, shard the fine-tuning estimators across ranks to reduce per-rank activation memory. Defaults to `False`. |
  | <span id="finetunedtabpfnregressor--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/regressor#finetunedtabpfnregressor-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="finetunedtabpfnregressor--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="finetunedtabpfnregressor--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` | — |
  | <span id="finetunedtabpfnregressor--extra-regressor-kwargs" /><code className="python-reference-parameter">extra\_<wbr />regressor\_<wbr />kwargs</code> | <code className="python-reference-type">dict\[str, Any] \| None</code><br /><a href="/api-reference/python/tabpfn/regressor/configuration#constructor"><code>TabPFNRegressor</code> options</a> | `None` | Additional keyword arguments to pass to the underlying [`TabPFNRegressor`](/api-reference/python/tabpfn/regressor/configuration#constructor), such as `n_estimators`. |
  | <span id="finetunedtabpfnregressor--ce-loss-weight" /><code className="python-reference-parameter">ce\_<wbr />loss\_<wbr />weight</code> | <code className="python-reference-type">float</code> | `0.0` | Weight for the bar distribution negative log-likelihood term (cross-entropy-like). Defaults to `0.0`. |
  | <span id="finetunedtabpfnregressor--crps-loss-weight" /><code className="python-reference-parameter">crps\_<wbr />loss\_<wbr />weight</code> | <code className="python-reference-type">float</code> | `1.0` | Weight for the continuous ranked probability score (CRPS) term computed on ordered bar probabilities (squared CDF error). Defaults to `1.0`. |
  | <span id="finetunedtabpfnregressor--crls-loss-weight" /><code className="python-reference-parameter">crls\_<wbr />loss\_<wbr />weight</code> | <code className="python-reference-type">float</code> | `0.0` | Weight for the continuous ranked logarithmic score (CRLS) term computed on ordered bar probabilities (log score on cumulative probabilities). Defaults to `0.0`. |
  | <span id="finetunedtabpfnregressor--mse-loss-weight" /><code className="python-reference-parameter">mse\_<wbr />loss\_<wbr />weight</code> | <code className="python-reference-type">float</code> | `1.0` | Weight for an auxiliary MSE loss term added to the bar distribution loss. Set to 0.0 to disable. Defaults to `1.0`. |
  | <span id="finetunedtabpfnregressor--mse-loss-clip" /><code className="python-reference-parameter">mse\_<wbr />loss\_<wbr />clip</code> | <code className="python-reference-type">float \| None</code> | `None` | Optional upper bound for the auxiliary MSE loss term. If `None`, no clipping is applied. Defaults to `None`. |
  | <span id="finetunedtabpfnregressor--mae-loss-weight" /><code className="python-reference-parameter">mae\_<wbr />loss\_<wbr />weight</code> | <code className="python-reference-type">float</code> | `0.0` | Weight for an auxiliary MAE term computed on the mean decoded prediction. Defaults to `0.0`. |
  | <span id="finetunedtabpfnregressor--mae-loss-clip" /><code className="python-reference-parameter">mae\_<wbr />loss\_<wbr />clip</code> | <code className="python-reference-type">float \| None</code> | `None` | Optional upper bound for the auxiliary MAE loss term. If `None`, no clipping is applied. Defaults to `None`. |
  | <span id="finetunedtabpfnregressor--eval-metric" /><code className="python-reference-parameter">eval\_<wbr />metric</code> | <code className="python-reference-type">Literal\["mse"] \| None</code> | `None` | The evaluation metric to use for early stopping and monitoring. For regression, the default is "mse". Other metrics are not currently supported. |
  | <span id="finetunedtabpfnregressor--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` | — |
</div>

***

<div className="python-reference-heading">
  <h2 id="finetunedtabpfnregressor-finetune-model-version">
    `FinetunedTabPFNRegressor.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 FinetunedTabPFNRegressor.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="finetunedtabpfnregressor-predict">
    `FinetunedTabPFNRegressor.predict`
  </h2>

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

Predict target values for `X`.

```python theme={null}
FinetunedTabPFNRegressor.predict(
    X: XType,
    **kwargs,
) -> RegressionResultType
```

<Accordion title="Type aliases">
  ```python theme={null}
  XType = Any
  RegressionResultType = np.ndarray | list[np.ndarray] | MainOutputDict | FullOutputDict
  ```
</Accordion>

**Parameters**

<div className="python-reference-table">
  | Parameter | Type | Default | Description |
  | - | - | - | - |
  | <span id="finetunedtabpfnregressor-predict--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 input samples of shape (n\_samples, n\_features). |
  | <span id="finetunedtabpfnregressor-predict--kwargs" /><code className="python-reference-parameter">\*\*kwargs</code> | —<br /><a href="/api-reference/python/tabpfn/regressor/fitting-and-prediction#predict"><code>predict</code> options</a> | — | Additional keyword arguments to pass to the underlying inference regressor (e.g., output\_type, quantiles). |
</div>

**Returns**

<div className="python-reference-table python-reference-returns">
  | Type | Description |
  | - | - |
  | <code className="python-reference-type"><a href="https://github.com/PriorLabs/TabPFN/blob/c70b6ef0488858d32244c52222abfc0c5be207d6/src/tabpfn/regressor.py#L171">Regression<wbr />Result<wbr />Type</a></code> | The predicted target values with shape (n\_samples,). |
</div>

***

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

  <a className="python-reference-source" href="https://github.com/PriorLabs/TabPFN/blob/c70b6ef0488858d32244c52222abfc0c5be207d6/src/tabpfn/finetuning/finetuned_regressor.py#L486" aria-label="View source for FinetunedTabPFNRegressor.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}
FinetunedTabPFNRegressor.fit(
    X: XType,
    y: YType,
    X_val: XType | None = None,
    y_val: YType | None = None,
    output_dir: Path | None = None,
) -> FinetunedTabPFNRegressor
```

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

**Parameters**

<div className="python-reference-table">
  | Parameter | Type | Default | Description |
  | - | - | - | - |
  | <span id="finetunedtabpfnregressor-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="finetunedtabpfnregressor-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="finetunedtabpfnregressor-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="finetunedtabpfnregressor-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="finetunedtabpfnregressor-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/regressor#finetunedtabpfnregressor">Finetuned<wbr />Tab<wbr />PFN<wbr />Regressor</a></code> | The fitted instance itself. |
</div>


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