{"id":8155,"library":"fiftyone-db","title":"FiftyOne DB","description":"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.","status":"active","version":"1.4.1","language":"en","source_language":"en","source_url":"https://github.com/voxel51/fiftyone","tags":["computer-vision","database","data-management","mongodb","machine-learning"],"install":[{"cmd":"pip install fiftyone-db","lang":"bash","label":"Install fiftyone-db"}],"dependencies":[{"reason":"Required for MongoDB interactions as the underlying database driver.","package":"pymongo","optional":false}],"imports":[{"note":"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.","wrong":"import fiftyone_db","symbol":"db","correct":"import fiftyone.db"}],"quickstart":{"code":"import fiftyone as fo\nimport fiftyone.zoo as foz\n\n# A quickstart for the main FiftyOne library, which implicitly uses fiftyone-db\ndataset = foz.load_zoo_dataset(\"quickstart\")\nsession = fo.launch_app(dataset)\nsession.wait() # Blocks execution until the App is closed if run in a script\n","lang":"python","description":"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."},"warnings":[{"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`.","message":"`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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions with data model changes"},{"fix":"Use `dataset.persistent = True` or `dataset.save()` to mark a dataset as persistent, or when creating, pass `persistent=True` to `fo.Dataset()`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Increase the open file limit by running `ulimit -n 64000` in your shell before starting FiftyOne.","message":"On some Unix systems, the default open file limit may be too small for FiftyOne's MongoDB connection, causing the database service to exit.","severity":"gotcha","affected_versions":"All versions on affected Unix systems"},{"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.","message":"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.","severity":"deprecated","affected_versions":"Older MongoDB versions (e.g., 5.0, 4.4); Python 3.9 for future releases"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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).","cause":"FiftyOne's internal MongoDB service is not running or is inaccessible, often due to MongoDB not being installed, started, or having port conflicts.","error":"pymongo.errors.ServerSelectionTimeoutError: localhost:27017: [Errno 111] Connection refused"},{"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`.","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.","error":"ModuleNotFoundError: No module named 'psutil'"},{"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`.","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).","error":"fiftyone.core.exceptions.DatasetNotFoundError: Dataset 'my-dataset' not found"},{"fix":"Install IPython directly into your active virtual environment: `pip install ipython`.","cause":"IPython is installed globally but FiftyOne is in a virtual environment, leading to potential module resolution issues.","error":"UserWarning: Attempting to work in a virtualenv. If you encounter problems, please install IPython inside the virtualenv."}]}