Neptune Client

1.14.0.post2 · active · verified Thu Apr 16

Neptune is an MLOps platform for experiment tracking and model management, focusing on machine learning metadata. The `neptune-client` Python library provides the interface to log, store, display, and compare MLOps artifacts and metadata directly from your code. It is currently at version 1.14.0.post2, with active development including an upcoming 2.x branch, and releases frequent updates.

Common errors

```
NeptuneMissingApiTokenException: 'NEPTUNE_API_TOKEN' environment variable not found. Please set it or pass `api_token` to `neptune.init_run()`.
```
cause The Neptune API token is not configured.

fix Set the `NEPTUNE_API_TOKEN` environment variable with your personal API token (found in Neptune UI, Account Settings -> API Tokens), or pass `api_token='YOUR_API_TOKEN'` directly to `neptune.init_run()`.
```
NeptuneMissingProjectException: 'NEPTUNE_PROJECT' environment variable not found. Please set it or pass `project` to `neptune.init_run()`.
```
cause The target Neptune project is not specified.

fix Set the `NEPTUNE_PROJECT` environment variable to your project's identifier (e.g., 'your_workspace/your_project'), or pass `project='your_workspace/your_project'` directly to `neptune.init_run()`.
```
AttributeError: module 'neptune' has no attribute 'init'
```
cause Attempting to use the old `neptune.init()` function which has been replaced.

fix Update your code to use `neptune.init_run()` instead of `neptune.init()`.

Warnings

breaking Python 3.7 is no longer supported. Ensure your environment uses Python 3.8 or newer.
Fix: Upgrade your Python environment to 3.8 or a later compatible version (e.g., 3.9, 3.10, 3.11).
deprecated The `model` and `model_version` endpoints within the Neptune API are deprecated. Users should migrate to the new `Model` and `ModelVersion` objects.
Fix: Refer to Neptune's official documentation for updated methods to manage models and model versions using the `neptune.init_model()` and `neptune.init_model_version()` functions.
gotcha The `neptune.init()` function is deprecated. Using it will lead to warnings and potentially errors in future versions.
Fix: Replace all instances of `neptune.init()` with `neptune.init_run()` for initializing experiment runs.
gotcha When uploading HTML objects with `run['path'].upload()` or using `File.as_html()`, the default behavior is to embed the entire Plotly.js library (approx. 3MB) within the HTML. For Neptune SaaS users, this can significantly increase object size.
Fix: For smaller HTML objects, especially with Neptune SaaS, pass `include_plotlyjs='cdn'` to the `upload()` or `as_html()` method, which loads Plotly.js from a CDN.
gotcha You must set the `NEPTUNE_API_TOKEN` and `NEPTUNE_PROJECT` environment variables or pass them directly to `neptune.init_run()` to connect to your Neptune project. Forgetting to do so is a common cause of connection errors.
Fix: Define `NEPTUNE_API_TOKEN` and `NEPTUNE_PROJECT` in your environment or explicitly pass `api_token` and `project` arguments to `neptune.init_run()`.

Install

pip install neptune Install stable version

Imports

init_run
wrong:
```
import neptune
run = neptune.init(...)
```
correct:
```
import neptune
run = neptune.init_run(...)
```
`neptune.init()` was the entry point in versions <1.0.0 and is now deprecated. Use `neptune.init_run()` for current versions.
Run
```
from neptune import Run
```
Can be used for type hinting or direct instantiation if desired, though `neptune.init_run()` is the primary way to get a Run object.

Quickstart

This quickstart initializes a Neptune run, logs basic parameters and metrics, tracks a placeholder for a model checkpoint, and then stops the run. Ensure you have your `NEPTUNE_API_TOKEN` and `NEPTUNE_PROJECT` (e.g., 'your_workspace/your_project') set as environment variables or passed directly to `init_run`.

import neptune
import os
import random

# Initialize a new Neptune run
# Replace 'YOUR_WORKSPACE/YOUR_PROJECT_NAME' with your actual project name, e.g., 'common/quickstart-python'
# Set NEPTUNE_API_TOKEN and NEPTUNE_PROJECT as environment variables for production use.
run = neptune.init_run(
    project=os.environ.get("NEPTUNE_PROJECT", "common/quickstart-python"),
    api_token=os.environ.get("NEPTUNE_API_TOKEN", "YOUR_NEPTUNE_API_TOKEN"), # Replace with your token if not using env var
    name="Minimal Example",
    tags=["quickstart", "example"]
)

# Log some parameters
params = {"learning_rate": 0.001, "optimizer": "Adam"}
run["parameters"] = params

# Log some metrics
for i in range(10):
    run["train/loss"].append(random.uniform(0.1, 0.9))
    run["train/accuracy"].append(random.uniform(0.5, 0.99))

# Log a model checkpoint placeholder (e.g., a path or a link)
run["model_checkpoints/best_model"].track_files("s3://my-bucket/models/best_model.pth")

# Stop the run
run.stop()

print(f"Neptune run URL: {run.get_url()}")

view raw JSON →