FiftyOne DB

1.4.1 · active · verified Thu Apr 16

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.

Common errors

```
pymongo.errors.ServerSelectionTimeoutError: localhost:27017: [Errno 111] Connection refused
```
cause 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'
```
cause 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
```
cause 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.
```
cause 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`.

Warnings

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`.
gotcha When 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.
gotcha By 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()`.
gotcha On 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.
deprecated FiftyOne 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.

Install

pip install fiftyone-db Install fiftyone-db

Imports

db
wrong:
```
import fiftyone_db
```
correct:
```
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.

Quickstart

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

view raw JSON →