neptune-scale

library0.30.0pypypi✓ verified 21d ago

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.

ai-ml llm-agents

pip install neptune-scale

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · NEPTUNE-SCALE

neptune-scale

ai-mlpythonv0.30.0

Install

5.9s avg

Import

1653ms

Disk

61MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.30.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 1.840s · 60.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 5.9s · import 1.466s · 62MB

61MB installed

● package 61MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Run

✓ from neptune_scale import Run

✗ import neptune; run = neptune.init_run()

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

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.")

Debug

Known issues

breakingMigration 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.

affects: All versions

breakingThe `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.

affects: >=0.24.0

gotchaThe 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.

affects: >=0.29.0

gotchaInitializing 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.

affects: All versions

gotchaAs 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`.

affects: >=0.29.0

Errors

Common errors & fixes

NeptuneApiTokenNotProvided

The Neptune client library could not find an API token, either through explicit arguments or environment variables.

fix

Set the `NEPTUNE_API_TOKEN` environment variable with your API token, or pass the token directly to the `neptune.init()` function.

NeptuneFailedToFetchClientConfig

This error typically occurs when the provided Neptune API token is invalid or has expired.

fix

Regenerate your Neptune API token from your Neptune workspace settings and update it in your environment variables or scripts.

ModuleNotFoundError: No module named 'neptune'

The `neptune` client library is not installed in the current Python environment or a legacy `neptune-client` version is causing conflicts.

fix

Install the `neptune-scale` library using `pip install neptune-scale`. If `neptune-client` was previously installed, uninstall it first (`pip uninstall neptune-client`) before installing `neptune-scale`.

AttributeError: module 'neptune.new' has no attribute 'init'

This error indicates that an older, deprecated `neptune.new` module is being used, or there's a version mismatch after upgrading the `neptune-scale` client.

fix

Ensure you are using the latest `neptune-scale` library and update your imports to use `from neptune_scale import init` or `import neptune_scale as neptune; neptune.init(...)`.

NeptuneFileUploadTemporaryError: A temporary error occurred during file upload

This error occurs when there's a transient issue during the upload of files to Neptune, often due to network problems or server-side temporary unavailability.

fix

This is often a temporary issue; retrying the operation or checking your internet connection might resolve it. Neptune's client has built-in retry logic, but persistent issues might require checking network stability or Neptune's service status.

Upgrade

Version history

0.30.0latest on PyPI · released Nov 26, 2025

Audit

Dependencies

neptune-apirequiredCore API communication library for Neptune.ai service.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/neptune-ai/neptune-client-scale ↗

packagehttps://pypi.org/project/neptune-scale/ ↗

homepagehttps://neptune.ai ↗

docshttps://docs.neptune.ai/ ↗