{"id":4646,"library":"neptune-scale","title":"neptune-scale Client Library","description":"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.","status":"active","version":"0.30.0","language":"en","source_language":"en","source_url":"https://github.com/neptune-ai/neptune-client-scale","tags":["MLOps","experiment tracking","Neptune.ai","client","deep learning"],"install":[{"cmd":"pip install neptune-scale","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core API communication library for Neptune.ai service.","package":"neptune-api","optional":false}],"imports":[{"note":"This is the pattern for the legacy `neptune` client (2.x). `neptune-scale` (3.x) uses the `Run` class directly from `neptune_scale`.","wrong":"import neptune; run = neptune.init_run()","symbol":"Run","correct":"from neptune_scale import Run"}],"quickstart":{"code":"import os\nfrom neptune_scale import Run\n\n# Set these environment variables before running:\n# os.environ['NEPTUNE_API_TOKEN'] = 'YOUR_NEPTUNE_API_TOKEN'\n# os.environ['NEPTUNE_PROJECT'] = 'YOUR_WORKSPACE/YOUR_PROJECT'\n\nif __name__ == '__main__':\n    try:\n        with Run(project=os.environ.get('NEPTUNE_PROJECT', '')) as run:\n            run['sys/tags'].add(['quickstart', 'example'])\n            run['config/learning_rate'] = 0.001\n            for i in range(10):\n                run['metrics/loss'].append(0.9 - i * 0.05)\n            print(f\"Neptune run URL: {run.get_url()}\")\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n        print(\"Please ensure NEPTUNE_API_TOKEN and NEPTUNE_PROJECT environment variables are set correctly.\")","lang":"python","description":"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."},"warnings":[{"fix":"Consult the official Neptune.ai migration guide for detailed instructions on updating your codebase.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Remove the `resume` parameter from `Run()` calls. Provide `run_id` to resume an existing run.","message":"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.","severity":"breaking","affected_versions":">=0.24.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.29.0"},{"fix":"Wrap your Neptune `Run` initialization and main logic within an `if __name__ == '__main__':` block.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If strict error handling for non-finite values is required, set the environment variable `NEPTUNE_INVALID_VALUE_ACTION=raise`.","message":"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.","severity":"gotcha","affected_versions":">=0.29.0"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}