Neptune Client

1.14.0.post2 · active · verified Thu Apr 16

Neptune Client is the Python library for interacting with Neptune.ai, an MLOps platform for experiment tracking and model management. It allows users to log, organize, and visualize machine learning metadata, including hyperparameters, metrics, and artifacts. The current version is 1.14.0.post2, and the library is actively maintained with frequent releases.

Common errors

```
NeptuneApiTokenNotProvided: Your Neptune API token was not found.
```
cause The Neptune client could not find the API token. It's usually expected as an environment variable (NEPTUNE_API_TOKEN) or passed directly to `neptune.init_run()`.

fix Set the `NEPTUNE_API_TOKEN` environment variable with your token from Neptune.ai, or pass it explicitly: `neptune.init_run(api_token='YOUR_TOKEN', ...)`.
```
RuntimeError: We've detected that the 'neptune' and 'neptune-client' packages are both installed. Uninstall each of them and then install only the new 'neptune' package.
```
cause Conflicting installations of the old (`neptune-client`) and new (`neptune`) library packages are present in the environment.

fix Run `pip uninstall neptune-client neptune` to remove both, then `pip install neptune` to install the recommended package for current versions.
```
NeptuneConnectionLostException: Neptune client lost connection to the server.
```
cause This typically indicates network issues, server downtime, or firewall blocks preventing the client from reaching the Neptune server.

fix Check your network connection, ensure the Neptune server URL is correct, and verify no firewalls are blocking access. For self-hosted instances, check server status and Nginx keep-alive settings.
```
TypeError: argument of type '...' is not iterable
```
cause When using logging methods like `log_configs()` or `log_metrics()`, an argument of an incorrect type (e.g., string instead of a float for metrics) was passed.

fix Ensure that the data types passed to logging methods match the expected types (e.g., numbers for metrics, dictionaries for configurations).
```
ValueError: Invalid value for run ID. Run ID cannot be empty or too long.
```
cause An invalid or malformed Run ID was provided, often when trying to set a custom run ID.

fix Ensure the custom `run_id` is a non-empty string and within the allowed length limits. Neptune auto-generates one if not provided.

Warnings

breaking For Neptune client versions 1.x and later, the recommended package name is `neptune`, not `neptune-client`. Installing both or installing `neptune` over `neptune-client` can lead to issues. It's strongly advised to `pip uninstall neptune-client` and then `pip install neptune`.
Fix: Run `pip uninstall neptune-client neptune` then `pip install neptune`.
breaking The `neptune.new` package and imports (e.g., `import neptune.new as neptune`) were removed in version 1.0. The main API is now directly under `neptune` (e.g., `import neptune`). The `neptune.legacy` package, containing the 0.x API, is also removed/deprecated.
Fix: Update import statements from `neptune.new` to `neptune`. If using the old API, consult migration guides.
breaking Starting with version 1.0, Neptune no longer implicitly casts unsupported Python types to `String` when logging. Attempting to log an unsupported type will result in the value being skipped and a warning printed.
Fix: Explicitly convert unsupported types to strings using `str(value)` or use `neptune.types.stringify_unsupported(value)` if you intend to log them as strings.
breaking Many package-level functions in `neptune` and `neptune.management` now require keyword arguments (named arguments) instead of positional arguments. This change does not affect logging methods like `upload()` or `append()`.
Fix: Ensure all arguments to package-level functions are passed as keyword arguments (e.g., `neptune.init_run(project='...', api_token='...')` instead of `neptune.init_run('...', '...')`).
deprecated Support for Python 3.7 was dropped in `neptune-client` version 1.12.0.
Fix: Upgrade your Python environment to version 3.8 or higher.
deprecated The `model` and `model_version` endpoints were deprecated starting from version 1.12.0.
Fix: Consult Neptune's official documentation for alternative ways to manage models and model versions, or continue using older versions if these endpoints are critical to your workflow.
gotcha When using `upload()` or `File.as_html()` to log Plotly figures, the `include_plotlyjs` argument defaults to `True`, which embeds the Plotly.js source code in the HTML, increasing file size by ~3MB. For Neptune SaaS users, using CDN is recommended.
Fix: Pass `include_plotlyjs='cdn'` to the `upload()` or `File.as_html()` methods to link to Plotly.js from a CDN instead of embedding it directly.

Install

pip install neptune-client Install neptune-client

Imports

init_run
wrong:
```
import neptune.new as neptune
```
correct:
```
import neptune
run = neptune.init_run(...)
```
For `neptune-client` versions 1.0+ (or the `neptune` package), the main import is `import neptune`. `neptune.new` was for transitioning from 0.x to 1.x and is now deprecated.
Run
wrong:
```
from neptune.new import Run
```
correct:
```
from neptune import Run
run = Run(...)
```
Similar to `init_run`, direct import from `neptune` is the standard for 1.0+.

Quickstart

This quickstart demonstrates how to initialize a Neptune run, log hyperparameters, track metrics over time, and upload an artifact. It assumes `NEPTUNE_API_TOKEN` and `NEPTUNE_PROJECT` are set as environment variables for authentication and project selection. If not, replace the placeholders with your actual token and project name. The code creates a local 'sample_output.txt' file and uploads it as an artifact.

import neptune
import os

# Replace with your actual API token and project name
# It is recommended to set NEPTUNE_API_TOKEN and NEPTUNE_PROJECT as environment variables
# os.environ["NEPTUNE_API_TOKEN"] = "YOUR_NEPTUNE_API_TOKEN"
# os.environ["NEPTUNE_PROJECT"] = "YOUR_WORKSPACE/YOUR_PROJECT"

# Initialize a Neptune run
run = neptune.init_run(
    project=os.environ.get('NEPTUNE_PROJECT', 'common/quickstarts'), # Replace with your workspace and project name
    api_token=os.environ.get('NEPTUNE_API_TOKEN', ''), # Replace with your API token or set env variable
    name='my-first-run',
    tags=['quickstart', 'example']
)

# Log hyperparameters
hparams = {
    'learning_rate': 0.001,
    'epochs': 10,
    'batch_size': 32
}
run['hyperparameters'] = hparams

# Log metrics
for i in range(10):
    run['metrics/accuracy'].append(0.85 + i * 0.01)
    run['metrics/loss'].append(0.3 - i * 0.02)

# Log a file
with open('sample_output.txt', 'w') as f:
    f.write('This is a sample output file.')
run['artifacts/output_file'].upload('sample_output.txt')

# Stop the run
run.stop()

view raw JSON →