docs/en/integrations/neptune.md
!!! warning "Neptune acquisition and SaaS deprecation"
Neptune has entered into an agreement to be acquired by OpenAI and will wind down its hosted (SaaS) service after a transition period ending March 4, 2026. Review the [official announcement](https://neptune.ai/blog/we-are-joining-openai) and plan migrations or exports accordingly.
Neptune is a metadata store for MLOps, built for teams that run a lot of experiments. It gives you a single place to log, store, display, organize, compare, and query all your model building metadata.
Ultralytics YOLO26 integrates with Neptune to streamline experiment tracking. This integration allows you to automatically log training metrics, visualize model predictions, and store model artifacts without writing custom logging code.
<p align="center"> </p>best.pt) automatically at the end of training.To use Neptune with Ultralytics, you will need to install the neptune client package along with ultralytics.
!!! tip "Installation"
=== "CLI"
```bash
# Install the required packages
pip install ultralytics neptune
# Enable Neptune integration in Ultralytics settings
yolo settings neptune=True
```
Before you start training, you need to connect your local environment to your Neptune project. You will need your API Token and Project Name from your Neptune dashboard.
The securest way to handle credentials is via environment variables. Note that the Ultralytics Neptune callback reads the YOLO project argument and does not use NEPTUNE_PROJECT. Pass the full Neptune slug (e.g., workspace/name) via project= in your training command; otherwise Neptune will try to use the literal default "Ultralytics" and the run will fail.
=== "Bash (Linux/Mac)"
```bash
export NEPTUNE_API_TOKEN="your_long_api_token_here" # required
```
=== "PowerShell (Windows)"
```powershell
$Env:NEPTUNE_API_TOKEN = "your_long_api_token_here" # required
```
=== "Python"
```python
import os
os.environ["NEPTUNE_API_TOKEN"] = "your_long_api_token_here"
```
Once configured, you can start training your YOLO26 models. The Neptune integration works automatically when the neptune package is installed and the integration is enabled in settings.
!!! example "Train YOLO26 with Neptune Logging"
=== "Python"
```python
from ultralytics import YOLO
# Load a model
model = YOLO("yolo26n.pt")
# Train the model
# Pass the Neptune project slug as the 'project' argument (workspace/name)
results = model.train(data="coco8.yaml", epochs=10, project="my-workspace/my-project", name="experiment-1")
```
=== "CLI"
```bash
# Train via CLI
# project must be the Neptune slug (workspace/name); otherwise run creation will fail
yolo train data=coco8.yaml epochs=10 project=my-workspace/my-project name=experiment-1
```
The following diagram illustrates how the Ultralytics Training pipeline interacts with Neptune to log various artifacts and metrics.
graph LR
A[YOLO Training Loop] --> B{Neptune Callback}
B -->|Log Scalars| C[Loss, mAP, LR]
B -->|Log Images| D[Mosaics, Preds]
B -->|Log Artifacts| E[Model Weights]
B -->|Log Metadata| F[Hyperparameters]
C --> G[Neptune Server]
D --> G
E --> G
F --> G
G --> H[Neptune Web Dashboard]
When you run the training command, the Neptune integration automatically captures the following data structure in your run:
box_loss, cls_loss, dfl_loss, lr (learning rate).precision, recall, mAP50, mAP50-95.Mosaic: Training batches showing data augmentation.Validation: Ground truth labels and model predictions on validation data.Plots: Confusion matrices, Precision-Recall curves.best.pt) is uploaded to the weights folder in the Neptune run.You can use the standard Ultralytics project and name arguments to organize your runs in Neptune.
project: Must be the Neptune project slug workspace/name; this is what the callback passes to neptune.init_run.name: Acts as the identifier for the specific run.If you need to log additional custom metrics alongside the automatic logging, you can access the Neptune run instance. Note that you will need to modify the trainer logic or create a custom callback to access the specific run object, as the Ultralytics integration handles the run lifecycle internally.
If you have installed neptune but wish to disable logging for a specific session or globally, you can modify the YOLO settings.
# Disable Neptune integration
yolo settings neptune=False
Ensure that your network allows connections to Neptune's servers. Additionally, image logging usually occurs at specific intervals (e.g., end of epochs or end of training). If you interrupt training early using Ctrl+C, some final artifacts like confusion matrices or the best model weights might not be uploaded.
The current integration automatically creates a new run for each training session. To resume logging to an existing run, you would typically need to handle the Neptune initialization manually in Python code, which falls outside the scope of the automatic integration. However, Ultralytics supports resuming training locally, which will create a new run in Neptune to track the resumed epochs.
In your Neptune dashboard, navigate to the Artifacts or All Metadata section. You will find a weights folder containing your best.pt file, which you can download for deployment.