NucliaDB Utils

6.13.0.post6185 verified Fri May 01 auth: no python

NucliaDB Utils is a utility library for NucliaDB, providing common functionalities such as authentication, storage abstraction, and messaging utilities. The latest version is 6.13.0.post6185, with frequent releases following NucliaDB's development cycle.

pip install nucliadb-utils

Common errors

error ModuleNotFoundError: No module named 'nucliadb_utils' ↓

cause Installed package 'nucliadb-utils' but Python module uses underscores.

fix

Install correctly with 'pip install nucliadb-utils' and import as 'nucliadb_utils'.

error ImportError: cannot import name 'NucliaUtility' from 'nucliadb_utils' ↓

cause Direct import from top-level package instead of submodule.

fix

Use 'from nucliadb_utils.utilities import NucliaUtility'.

Warnings

breaking Module name changed from 'nucliadb_utils' (note underscores) to maintain consistency. Ensure imports use underscores. ↓

fix Use 'nucliadb_utils' instead of 'nucliadb-utils' in Python imports.

deprecated The utility function 'get_nuclia_utility' is deprecated since v6.10.0. Use 'NucliaUtility' class directly. ↓

fix Replace with: from nucliadb_utils.utilities import NucliaUtility

gotcha Settings class requires explicit environment variables. Missing NUCLIA_SERVICE_ACCOUNT_TOKEN may cause authentication errors. ↓

fix Set NUCLIA_SERVICE_ACCOUNT_TOKEN or pass it to Settings constructor.

Imports

NucliaUtility

wrong

from nucliadb_utils import NucliaUtility

correct

from nucliadb_utils.utilities import NucliaUtility

NucliaUtility is in the utilities submodule.

Quickstart

Initialize settings with environment variables (authentication via service account token).

from nucliadb_utils.settings import Settings

settings = Settings(
    nuclia_service_account_token=os.environ.get('NUCLIA_SERVICE_ACCOUNT_TOKEN', ''),
    nuclia_cluster_url=os.environ.get('NUCLIA_CLUSTER_URL', 'http://localhost:8080')
)
print(f"NucliaDB URL: {settings.nuclia_cluster_url}")