{"id":8346,"library":"neptune-client","title":"Neptune Client","description":"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.","status":"active","version":"1.14.0.post2","language":"en","source_language":"en","source_url":"https://github.com/neptune-ai/neptune-client","tags":["MLOps","experiment tracking","machine learning","model management","AI"],"install":[{"cmd":"pip install neptune-client","lang":"bash","label":"Install neptune-client"}],"dependencies":[{"reason":"Requires Python 3.8 or newer for neptune-client versions >= 1.12.0.","package":"Python","optional":false}],"imports":[{"note":"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.","wrong":"import neptune.new as neptune","symbol":"init_run","correct":"import neptune\nrun = neptune.init_run(...)"},{"note":"Similar to `init_run`, direct import from `neptune` is the standard for 1.0+.","wrong":"from neptune.new import Run","symbol":"Run","correct":"from neptune import Run\nrun = Run(...)"}],"quickstart":{"code":"import neptune\nimport os\n\n# Replace with your actual API token and project name\n# It is recommended to set NEPTUNE_API_TOKEN and NEPTUNE_PROJECT as environment variables\n# os.environ[\"NEPTUNE_API_TOKEN\"] = \"YOUR_NEPTUNE_API_TOKEN\"\n# os.environ[\"NEPTUNE_PROJECT\"] = \"YOUR_WORKSPACE/YOUR_PROJECT\"\n\n# Initialize a Neptune run\nrun = neptune.init_run(\n    project=os.environ.get('NEPTUNE_PROJECT', 'common/quickstarts'), # Replace with your workspace and project name\n    api_token=os.environ.get('NEPTUNE_API_TOKEN', ''), # Replace with your API token or set env variable\n    name='my-first-run',\n    tags=['quickstart', 'example']\n)\n\n# Log hyperparameters\nhparams = {\n    'learning_rate': 0.001,\n    'epochs': 10,\n    'batch_size': 32\n}\nrun['hyperparameters'] = hparams\n\n# Log metrics\nfor i in range(10):\n    run['metrics/accuracy'].append(0.85 + i * 0.01)\n    run['metrics/loss'].append(0.3 - i * 0.02)\n\n# Log a file\nwith open('sample_output.txt', 'w') as f:\n    f.write('This is a sample output file.')\nrun['artifacts/output_file'].upload('sample_output.txt')\n\n# Stop the run\nrun.stop()","lang":"python","description":"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."},"warnings":[{"fix":"Run `pip uninstall neptune-client neptune` then `pip install neptune`.","message":"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`.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Update import statements from `neptune.new` to `neptune`. If using the old API, consult migration guides.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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('...', '...')`).","message":"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()`.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Upgrade your Python environment to version 3.8 or higher.","message":"Support for Python 3.7 was dropped in `neptune-client` version 1.12.0.","severity":"deprecated","affected_versions":">=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.","message":"The `model` and `model_version` endpoints were deprecated starting from version 1.12.0.","severity":"deprecated","affected_versions":">=1.12.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.13.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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', ...)`.","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()`.","error":"NeptuneApiTokenNotProvided: Your Neptune API token was not found."},{"fix":"Run `pip uninstall neptune-client neptune` to remove both, then `pip install neptune` to install the recommended package for current versions.","cause":"Conflicting installations of the old (`neptune-client`) and new (`neptune`) library packages are present in the environment.","error":"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."},{"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.","cause":"This typically indicates network issues, server downtime, or firewall blocks preventing the client from reaching the Neptune server.","error":"NeptuneConnectionLostException: Neptune client lost connection to the server."},{"fix":"Ensure that the data types passed to logging methods match the expected types (e.g., numbers for metrics, dictionaries for configurations).","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.","error":"TypeError: argument of type '...' is not iterable"},{"fix":"Ensure the custom `run_id` is a non-empty string and within the allowed length limits. Neptune auto-generates one if not provided.","cause":"An invalid or malformed Run ID was provided, often when trying to set a custom run ID.","error":"ValueError: Invalid value for run ID. Run ID cannot be empty or too long."}]}