fiftyone-db

library1.4.1pypypi✓ verified 91d ago

FiftyOne DB is the underlying database backend component for the FiftyOne computer vision framework, storing metadata about datasets and samples. It primarily relies on MongoDB. The current PyPI version is 1.4.1. While `fiftyone-db` is a specific PyPI package, it acts as an internal dependency for the main `fiftyone` library, which has a rapid release cadence (e.g., currently at `1.14.x`). Users typically interact with the database layer through the `fiftyone` package itself.

database ai-ml

pip install fiftyone-db

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FIFTYONE-DB

fiftyone-db

databasepythonv1.4.1

Install

3.2s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4.1 · 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

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 3.2s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import fiftyone.db

✗ import fiftyone_db

Direct imports from the `fiftyone-db` package are generally not intended for end-users. Instead, database-level interactions are exposed through the `fiftyone.db` submodule of the main `fiftyone` library.

The `fiftyone-db` package is an internal component. User interaction typically happens through the main `fiftyone` library. This quickstart demonstrates loading a dataset and launching the FiftyOne App, which utilizes `fiftyone-db` under the hood.

import fiftyone as fo import fiftyone.zoo as foz # A quickstart for the main FiftyOne library, which implicitly uses fiftyone-db dataset = foz.load_zoo_dataset("quickstart") session = fo.launch_app(dataset) session.wait() # Blocks execution until the App is closed if run in a script

Debug

Known issues

breaking`fiftyone-db` (and thus `fiftyone`) requires a running MongoDB instance. Failure to install or properly configure MongoDB will prevent the library from functioning, often resulting in connection errors on import.

fix

Ensure MongoDB (version 6.0+ recommended) is installed and running, and accessible by the FiftyOne client. For custom MongoDB, set `FIFTYONE_DATABASE_URI` or `database_uri` in `~/.fiftyone/config.json`.

affects: All versions

gotchaWhen working with `fiftyone` (which uses `fiftyone-db`), new versions occasionally introduce data model changes that require database migrations. While upgrades are often automatic, downgrades require manual migration using `fiftyone migrate --all -v <VERSION>` before installing the older version.

fix

Always check release notes for migration instructions when upgrading or downgrading. For downgrades, use `fiftyone migrate --all -v <VERSION>` before changing the `fiftyone` package version.

affects: All versions with data model changes

gotchaBy default, datasets in FiftyOne are non-persistent and are deleted from the database when all Python sessions importing FiftyOne exit. Explicitly persist datasets if you need them to be available across sessions.

fix

Use `dataset.persistent = True` or `dataset.save()` to mark a dataset as persistent, or when creating, pass `persistent=True` to `fo.Dataset()`.

affects: All versions

gotchaOn some Unix systems, the default open file limit may be too small for FiftyOne's MongoDB connection, causing the database service to exit.

fix

Increase the open file limit by running `ulimit -n 64000` in your shell before starting FiftyOne.

affects: All versions on affected Unix systems

deprecatedFiftyOne is designed for MongoDB v6.0 or later. Support for older MongoDB versions (e.g., 5.0, 4.4) has ended or is ending soon. Compatibility with Python 3.9 might also end after June 1, 2026.

fix

Upgrade to MongoDB v6.0 or later. For Python, ensure you are using Python 3.10-3.12 (as of current FiftyOne versions) and plan for Python 3.9 deprecation.

affects: Older MongoDB versions (e.g., 5.0, 4.4); Python 3.9 for future releases

Errors

Common errors & fixes

pymongo.errors.ServerSelectionTimeoutError: localhost:27017: [Errno 111] Connection refused

FiftyOne's internal MongoDB service is not running or is inaccessible, often due to MongoDB not being installed, started, or having port conflicts.

fix

Ensure MongoDB is installed and running. If using a custom MongoDB, verify the `FIFTYONE_DATABASE_URI` environment variable or `database_uri` in your FiftyOne config is correct. Check for other processes using port 27017 (default MongoDB port).

ModuleNotFoundError: No module named 'psutil'

The `psutil` package, a dependency of FiftyOne, might be missing or not correctly installed in the environment. This is common in some Linux setups or when virtual environments are not fully activated.

fix

Install `psutil` in your active virtual environment: `pip install psutil`. On Debian-based Linux, `python3-dev` might also be needed: `sudo apt install python3-dev`.

fiftyone.core.exceptions.DatasetNotFoundError: Dataset 'my-dataset' not found

Attempting to load a dataset that does not exist or has been deleted (e.g., if it was non-persistent and the Python session exited).

fix

Verify the dataset name using `fo.list_datasets()`. If the dataset was non-persistent, re-import it from its source files. If it was meant to be persistent, ensure it was saved with `dataset.persistent = True`.

UserWarning: Attempting to work in a virtualenv. If you encounter problems, please install IPython inside the virtualenv.

IPython is installed globally but FiftyOne is in a virtual environment, leading to potential module resolution issues.

fix

Install IPython directly into your active virtual environment: `pip install ipython`.

Upgrade

Version history

1.4.1latest on PyPI · released Dec 30, 2025

Audit

Dependencies

pymongorequiredRequired for MongoDB interactions as the underlying database driver.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/voxel51/fiftyone ↗

packagehttps://pypi.org/project/fiftyone-db/ ↗

homepagehttps://fiftyone.ai ↗