Install & Compatibility
Where this runs
tested against v0.23.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.704s · 201.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 11.3s · import 1.366s · 195MB
204MB installed
● package 204MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ReadOnlyProject
✓ from neptune_fetcher import ReadOnlyProject
✗ from neptune_fetcher import get_project
ReadOnlyRun
✓ from neptune_fetcher import ReadOnlyRun
✗ from neptune_fetcher import get_run
This quickstart demonstrates how to initialize a Neptune project using `neptune-client` and then use `neptune-fetcher`'s `get_project` to fetch run data. It explicitly warns about the library's deprecation and recommends `neptune-query`.
import neptune
from neptune_fetcher import get_project
import os
# NOTE: This library is deprecated. Use `neptune-query` instead.
# Ensure NEPTUNE_API_TOKEN and NEPTUNE_PROJECT are set as environment variables
# Initialize a Neptune project session (from neptune-client)
project_name = os.environ.get('NEPTUNE_PROJECT', 'common/quick-start') # Replace with your project
project_api_token = os.environ.get('NEPTUNE_API_TOKEN', 'ANONYMOUS')
if project_api_token == 'ANONYMOUS':
print("Warning: Using anonymous access. Please set NEPTUNE_API_TOKEN for full functionality.")
# The neptune.init_project call is from neptune-client, required to authenticate
neptune_project = neptune.init_project(
project=project_name,
api_token=project_api_token,
mode="read-only"
)
print(f"Initialized Neptune Project: {neptune_project.full_id}")
# Use neptune-fetcher to get the project handler
fetcher_project = get_project(project=neptune_project.full_id)
# Fetch runs data as a Pandas DataFrame
runs_df = fetcher_project.fetch_runs_df(columns=['sys/name', 'training/acc'], states=['succeeded'])
print(f"Fetched {len(runs_df)} runs.")
if not runs_df.empty:
print(runs_df.head())
# Stop the Neptune project session
neptune_project.stop()
Debug
Known issues
breakingThe `neptune-fetcher` library is officially deprecated. Users are strongly advised to migrate to the `neptune-query` library for future development and maintenance. The `neptune-fetcher` will receive only critical bug fixes and dependency updates, with no new features.fixMigrate your code to use `neptune-query`. Install with `pip install neptune-query` and refer to its documentation for updated usage patterns. The `get_project` and `fetch_*_df` methods have similar counterparts in `neptune-query` but with potentially different arguments and return types.
affects: 0.21.0 and later
gotchaPython compatibility is limited to versions 3.9 and higher, but strictly less than 4.0. Users on older Python versions (e.g., 3.8) or attempting to use it with Python 4.0 (if released) will encounter installation or runtime errors.fixEnsure your environment uses a compatible Python version (3.9, 3.10, 3.11, 3.12). Consider updating your Python environment or using virtual environments.
affects: All versions
gotchaPrior to version 0.22.0, fetching large DataFrames could lead to `PerformanceWarning` due to inefficient column insertion, potentially impacting performance with very wide datasets.fixUpgrade to `neptune-fetcher` version 0.22.0 or higher to benefit from performance improvements in DataFrame creation. Better yet, migrate to `neptune-query` which has optimized data handling.
affects: <0.22.0
gotchaDefault soft/hard retry timeouts for API calls were significantly increased in versions 0.20.1 and 0.21.0-beta.2/1. This can affect how long operations might hang before failing in case of network issues or server unresponsiveness.fixUpdate to `neptune-fetcher` 0.20.1 or newer to get updated default retry timeouts. If you need fine-grained control, consider implementing custom retry logic or checking for configuration options within the underlying `neptune-api`.
affects: <0.20.1
Upgrade
Version history
0.23.0latest on PyPI · released Sep 18, 2025
Audit
Dependencies
neptune-apirequiredCore dependency for interacting with the Neptune.ai backend.
pandasrequiredUsed for structuring fetched data into DataFrames.