neptune-scale Client Library

0.30.0 · active · verified Sun Apr 12

neptune-scale is the official Python client library for Neptune.ai, an MLOps platform for experiment tracking and model management. It enables users to log, visualize, and compare machine learning metadata such as metrics, parameters, and files at scale, especially designed for foundation model training. The library is actively developed, with the current stable version being 0.30.0 and frequent alpha/beta releases.

Warnings

breaking Migration from the legacy `neptune` client (version 2.x) to `neptune-scale` (version 3.x) requires significant code changes. Initialization (e.g., `neptune.init_run()` to `neptune_scale.Run()`), run lifecycle management (`run.stop()` to `run.close()`), and attribute logging methods have changed.
Fix: Consult the official Neptune.ai migration guide for detailed instructions on updating your codebase.
breaking The `resume` parameter was removed from the `Run` constructor in API version 0.24.0. If a `run_id` is provided, Neptune now implicitly attempts to resume the run; otherwise, a new run is created.
Fix: Remove the `resume` parameter from `Run()` calls. Provide `run_id` to resume an existing run.
gotcha The behavior of the `RUN_CONFLICTING` error changed in version 0.29.0. It is now treated as a warning instead of a fatal error, which might alter expected error handling in existing applications.
Fix: Review existing error handling logic for `RUN_CONFLICTING` scenarios. Adjust if you expect an exception to be raised, or update monitoring to check for warnings.
gotcha Initializing the `Run` object within an `if __name__ == '__main__':` block is strongly recommended. This practice ensures safe importing and correct behavior, especially in multi-process or distributed environments.
Fix: Wrap your Neptune `Run` initialization and main logic within an `if __name__ == '__main__':` block.
gotcha As of approximately 0.29.0, logging non-finite metric values (e.g., NaN or Inf) now defaults to skipping these values with a warning instead of raising an exception. This behavior can be controlled by the `NEPTUNE_INVALID_VALUE_ACTION` environment variable.
Fix: If strict error handling for non-finite values is required, set the environment variable `NEPTUNE_INVALID_VALUE_ACTION=raise`.

Install

pip install neptune-scale Install stable version

Imports

Run
```
from neptune_scale import Run
```
This is the pattern for the legacy `neptune` client (2.x). `neptune-scale` (3.x) uses the `Run` class directly from `neptune_scale`.

Quickstart

This quickstart initializes a Neptune Run, logs a configuration parameter and a series of metric values. It demonstrates the recommended use of environment variables for API token and project name, and the 'main guard' for safe execution.

import os
from neptune_scale import Run

# Set these environment variables before running:
# os.environ['NEPTUNE_API_TOKEN'] = 'YOUR_NEPTUNE_API_TOKEN'
# os.environ['NEPTUNE_PROJECT'] = 'YOUR_WORKSPACE/YOUR_PROJECT'

if __name__ == '__main__':
    try:
        with Run(project=os.environ.get('NEPTUNE_PROJECT', '')) as run:
            run['sys/tags'].add(['quickstart', 'example'])
            run['config/learning_rate'] = 0.001
            for i in range(10):
                run['metrics/loss'].append(0.9 - i * 0.05)
            print(f"Neptune run URL: {run.get_url()}")
    except Exception as e:
        print(f"An error occurred: {e}")
        print("Please ensure NEPTUNE_API_TOKEN and NEPTUNE_PROJECT environment variables are set correctly.")

view raw JSON →