Skip to content

Remove Neptune integration references and deprecate NeptuneCallback #42666

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
qgallouedec wants to merge 2 commits into
base: main
Choose a base branch
from
+15 −103
Open

Remove Neptune integration references and deprecate NeptuneCallback #42666

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8c164b7
Remove Neptune integration references and deprecate NeptuneCallback
qgallouedec Dec 5, 2025
8785d2e
Merge branch 'main' into deprecated-neptune
qgallouedec Dec 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 0 additions & 3 deletions docs/source/en/main_classes/callback.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,6 @@ By default, `TrainingArguments.report_to` is set to `"all"`, so a [`Trainer`] wi
- [`~integrations.WandbCallback`] if [wandb](https://www.wandb.com/) is installed.
- [`~integrations.CometCallback`] if [comet_ml](https://www.comet.com/site/) is installed.
- [`~integrations.MLflowCallback`] if [mlflow](https://www.mlflow.org/) is installed.
- [`~integrations.NeptuneCallback`] if [neptune](https://neptune.ai/) is installed.
- [`~integrations.AzureMLCallback`] if [azureml-sdk](https://pypi.org/project/azureml-sdk/) is
installed.
- [`~integrations.CodeCarbonCallback`] if [codecarbon](https://pypi.org/project/codecarbon/) is
Expand Down Expand Up @@ -84,8 +83,6 @@ Here is the list of the available [`TrainerCallback`] in the library:

[[autodoc]] integrations.CodeCarbonCallback

[[autodoc]] integrations.NeptuneCallback

[[autodoc]] integrations.ClearMLCallback

[[autodoc]] integrations.DagsHubCallback
Expand Down
3 changes: 0 additions & 3 deletions docs/source/ja/main_classes/callback.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,6 @@ rendered properly in your Markdown viewer.
- [`~integrations.WandbCallback`] [wandb](https://www.wandb.com/) がインストールされている場合。
- [`~integrations.CometCallback`] [comet_ml](https://www.comet.com/site/) がインストールされている場合。
- [mlflow](https://www.mlflow.org/) がインストールされている場合は [`~integrations.MLflowCallback`]。
- [`~integrations.NeptuneCallback`] [neptune](https://neptune.ai/) がインストールされている場合。
- [`~integrations.AzureMLCallback`] [azureml-sdk](https://pypi.org/project/azureml-sdk/) の場合
インストールされています。
- [`~integrations.CodeCarbonCallback`] [codecarbon](https://pypi.org/project/codecarbon/) の場合
Expand Down Expand Up @@ -82,8 +81,6 @@ rendered properly in your Markdown viewer.

[[autodoc]] integrations.CodeCarbonCallback

[[autodoc]] integrations.NeptuneCallback

[[autodoc]] integrations.ClearMLCallback

[[autodoc]] integrations.DagsHubCallback
Expand Down
3 changes: 0 additions & 3 deletions docs/source/ko/main_classes/callback.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,6 @@ rendered properly in your Markdown viewer.
사용됩니다.
- [`~integrations.CometCallback`]는 [comet_ml](https://www.comet.com/site/)이 설치되어 있으면 사용됩니다.
- [`~integrations.MLflowCallback`]는 [mlflow](https://www.mlflow.org/)가 설치되어 있으면 사용됩니다.
- [`~integrations.NeptuneCallback`]는 [neptune](https://neptune.ai/)이 설치되어 있으면 사용됩니다.
- [`~integrations.AzureMLCallback`]는 [azureml-sdk](https://pypi.org/project/azureml-sdk/)가 설치되어
있으면 사용됩니다.
- [`~integrations.CodeCarbonCallback`]는 [codecarbon](https://pypi.org/project/codecarbon/)이 설치되어
Expand Down Expand Up @@ -82,8 +81,6 @@ rendered properly in your Markdown viewer.

[[autodoc]] integrations.CodeCarbonCallback

[[autodoc]] integrations.NeptuneCallback

[[autodoc]] integrations.ClearMLCallback

[[autodoc]] integrations.DagsHubCallback
Expand Down
3 changes: 0 additions & 3 deletions docs/source/zh/main_classes/callback.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,6 @@ Callbacks是“只读”的代码片段，除了它们返回的[TrainerControl]
- [`~integrations.WandbCallback`]，如果安装了[wandb](https://www.wandb.com/)。
- [`~integrations.CometCallback`]，如果安装了[comet_ml](https://www.comet.com/site/)。
- [`~integrations.MLflowCallback`]，如果安装了[mlflow](https://www.mlflow.org/)。
- [`~integrations.NeptuneCallback`]，如果安装了[neptune](https://neptune.ai/)。
- [`~integrations.AzureMLCallback`]，如果安装了[azureml-sdk](https://pypi.org/project/azureml-sdk/)。
- [`~integrations.CodeCarbonCallback`]，如果安装了[codecarbon](https://pypi.org/project/codecarbon/)。
- [`~integrations.ClearMLCallback`]，如果安装了[clearml](https://github.com/allegroai/clearml)。
Expand Down Expand Up @@ -71,8 +70,6 @@ Callbacks是“只读”的代码片段，除了它们返回的[TrainerControl]

[[autodoc]] integrations.CodeCarbonCallback

[[autodoc]] integrations.NeptuneCallback

[[autodoc]] integrations.ClearMLCallback

[[autodoc]] integrations.DagsHubCallback
Expand Down
86 changes: 0 additions & 86 deletions examples/pytorch/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,7 +199,6 @@ You can easily log and monitor your runs code. The following are currently suppo
* [TensorBoard](https://www.tensorflow.org/tensorboard)
* [Weights & Biases](https://docs.wandb.ai/integrations/huggingface)
* [Comet ML](https://www.comet.com/docs/v2/integrations/ml-frameworks/transformers/)
* [Neptune](https://docs.neptune.ai/integrations-and-supported-tools/model-training/hugging-face)
* [ClearML](https://clear.ml/docs/latest/docs/getting_started/ds/ds_first_steps)
* [DVCLive](https://dvc.org/doc/dvclive/ml-frameworks/huggingface)

Expand Down Expand Up @@ -256,91 +255,6 @@ or if in a Conda environment:
conda install -c comet_ml -c anaconda -c conda-forge comet_ml
```

### Neptune

First, install the Neptune client library. You can do it with either `pip` or `conda`:

`pip`:

```bash
pip install neptune
```

`conda`:

```bash
conda install -c conda-forge neptune
```

Next, in your model training script, import `NeptuneCallback`:

```python
from transformers.integrations import NeptuneCallback
```

To enable Neptune logging, in your `TrainingArguments`, set the `report_to` argument to `"neptune"`:

```python
training_args = TrainingArguments(
"quick-training-distilbert-mrpc",
eval_strategy="steps",
eval_steps=20,
report_to="neptune",
)

trainer = Trainer(
model,
training_args,
...
)
```

**Note:** This method requires saving your Neptune credentials as environment variables (see the bottom of the section).

Alternatively, for more logging options, create a Neptune callback:

```python
neptune_callback = NeptuneCallback()
```

To add more detail to the tracked run, you can supply optional arguments to `NeptuneCallback`.

Some examples:

```python
neptune_callback = NeptuneCallback(
name = "DistilBERT",
description = "DistilBERT fine-tuned on GLUE/MRPC",
tags = ["args-callback", "fine-tune", "MRPC"], # tags help you manage runs in Neptune
base_namespace="callback", # the default is "finetuning"
log_checkpoints = "best", # other options are "last", "same", and None
capture_hardware_metrics = False, # additional keyword arguments for a Neptune run
)
```

Pass the callback to the Trainer:

```python
training_args = TrainingArguments(..., report_to=None)
trainer = Trainer(
model,
training_args,
...
callbacks=[neptune_callback],
)
```

Now, when you start the training with `trainer.train()`, your metadata will be logged in Neptune.

**Note:** Although you can pass your **Neptune API token** and **project name** as arguments when creating the callback, the recommended way is to save them as environment variables:

| Environment variable | Value |
| :------------------- | :--------------------------------------------------- |
| `NEPTUNE_API_TOKEN` | Your Neptune API token. To find and copy it, click your Neptune avatar and select **Get your API token**. |
| `NEPTUNE_PROJECT` | The full name of your Neptune project (`workspace-name/project-name`). To find and copy it, head to **project settings** → **Properties**. |

For detailed instructions and examples, see the [Neptune docs](https://docs.neptune.ai/integrations/transformers/).

### ClearML

To use ClearML, install the clearml package with:
Expand Down
10 changes: 10 additions & 0 deletions src/transformers/integrations/integration_utils.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
import shutil
import sys
import tempfile
import warnings
from dataclasses import fields
from enum import Enum
from pathlib import Path
Expand Down Expand Up @@ -1455,6 +1456,10 @@ def __init__(self):
class NeptuneCallback(TrainerCallback):
Copy link
Member

@tomaarsen tomaarsen Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not very familiar with the modern transformers deprecation approach, but do we have a nice decorator here that can inform IDE's that objects are deprecated, perhaps?
image

"""TrainerCallback that sends the logs to [Neptune](https://app.neptune.ai).

> [!WARNING]
> Neptune integration is deprecated and will be removed in a future version of Transformers. We recommend using
> other supported experiment tracking integrations.

Args:
api_token (`str`, *optional*): Neptune API token obtained upon registration.
You can leave this argument out if you have saved your token to the `NEPTUNE_API_TOKEN` environment
Expand Down Expand Up @@ -1500,6 +1505,11 @@ def __init__(
log_checkpoints: str | None = None,
**neptune_run_kwargs,
):
warnings.warn(
"The NeptuneCallback is deprecated and will be removed in a future version of Transformers. We recommend "
"using other supported experiment tracking integrations.",
FutureWarning,
)
if not is_neptune_available():
raise ValueError(
"NeptuneCallback requires the Neptune client library to be installed. "
Expand Down
10 changes: 5 additions & 5 deletions src/transformers/training_args.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -596,9 +596,9 @@ class TrainingArguments:
instance of `Dataset`.
report_to (`str` or `list[str]`, *optional*, defaults to `"none"`):
The list of integrations to report the results and logs to. Supported platforms are `"azure_ml"`,
`"clearml"`, `"codecarbon"`, `"comet_ml"`, `"dagshub"`, `"dvclive"`, `"flyte"`, `"mlflow"`, `"neptune"`,
`"swanlab"`, `"tensorboard"`, `"trackio"` and `"wandb"`. Use `"all"` to report to all integrations
installed, `"none"` for no integrations.
`"clearml"`, `"codecarbon"`, `"comet_ml"`, `"dagshub"`, `"dvclive"`, `"flyte"`, `"mlflow"`, `"swanlab"`,
`"tensorboard"`, `"trackio"` and `"wandb"`. Use `"all"` to report to all integrations installed, `"none"`
for no integrations.
project (`str`, *optional*, defaults to `"huggingface"`):
The name of the project to use for logging. Currently, only used by Trackio.
trackio_space_id (`str` or `None`, *optional*, defaults to `"trackio"`):
Expand Down Expand Up @@ -2386,8 +2386,8 @@ def set_logging(
report_to (`str` or `list[str]`, *optional*, defaults to `"none"`):
The list of integrations to report the results and logs to. Supported platforms are `"azure_ml"`,
`"clearml"`, `"codecarbon"`, `"comet_ml"`, `"dagshub"`, `"dvclive"`, `"flyte"`, `"mlflow"`,
`"neptune"`, `"swanlab"`, `"tensorboard"`, `"trackio"` and `"wandb"`. Use `"all"` to report to all
integrations installed, `"none"` for no integrations.
`"swanlab"`, `"tensorboard"`, `"trackio"` and `"wandb"`. Use `"all"` to report to all integrations
installed, `"none"` for no integrations.
first_step (`bool`, *optional*, defaults to `False`):
Whether to log and evaluate the first `global_step` or not.
nan_inf_filter (`bool`, *optional*, defaults to `True`):
Expand Down