Skip to content

FiftyOne - Dataset Visualization & Curation

Overview

The fiftyone command manages FiftyOne dataset visualization using Podman Quadlet containers. It includes a MongoDB sidecar for persistent dataset storage.

Key Concept: FiftyOne runs as a multi-container application with a MongoDB sidecar. The main FiftyOne container handles the web UI and processing, while MongoDB stores dataset metadata.

Quick Reference

Action Command Description
Config ujust fiftyone config [--port=...] [--bind=...] Configure instance
Start ujust fiftyone start [--instance=N\|all] Start FiftyOne + MongoDB
Stop ujust fiftyone stop [--instance=N\|all] Stop FiftyOne + MongoDB
Restart ujust fiftyone restart [--instance=N\|all] Restart all containers
Logs ujust fiftyone logs [--instance=N] [--lines=...] View interleaved logs
Status ujust fiftyone status [--instance=N] Show status (all instances)
URL ujust fiftyone url [--instance=N] Show access URL
Shell ujust fiftyone shell [--instance=N] [-- CMD...] Open shell in container
Plugins ujust fiftyone plugins [-- CMD...] Manage FiftyOne plugins
Delete ujust fiftyone delete [--instance=N\|all] Remove instance(s) and images

Parameters

Parameter Long Flag Short Default Description
action (positional) - required Action: config, start, stop, etc.
config_dir --config-dir -c ~/.config/fiftyone/{N} Configuration directory
workspace_dir --workspace-dir -w "" Optional mount to /workspace
bind --bind -b 127.0.0.1 Bind address
port --port -p 5151 Web UI port
image --image -i docker.io/voxel51/fiftyone Container image
tag --tag -t latest Image tag
gpu_type --gpu-type -g auto GPU type (auto/nvidia/amd/intel/none)
lines --lines -l 50 Log lines to show
instance --instance -n 1 Instance number

Configuration

# Default configuration (port 5151, localhost only)
ujust fiftyone config

# Custom port (long form)
ujust fiftyone config --port=5152

# Custom port (short form)
ujust fiftyone config -p 5152

# Network-wide access
ujust fiftyone config --bind=0.0.0.0

# With workspace mount
ujust fiftyone config --workspace-dir=/data/datasets

# Combine parameters (long form)
ujust fiftyone config --port=5152 --bind=0.0.0.0 --workspace-dir=/data

# Combine parameters (short form)
ujust fiftyone config -p 5152 -b 0.0.0.0 -w /data

Update Existing Configuration

Running config when already configured will update the existing configuration, preserving values not explicitly changed.

Lifecycle Commands

Start/Stop/Restart

# Start FiftyOne (includes MongoDB sidecar)
ujust fiftyone start

# Start specific instance (long form)
ujust fiftyone start --instance=1

# Start specific instance (short form)
ujust fiftyone start -n 1

# Start all instances
ujust fiftyone start --instance=all

# Stop FiftyOne + MongoDB
ujust fiftyone stop --instance=1

# Restart all containers
ujust fiftyone restart

View Logs

FiftyOne shows interleaved logs from both the main container and MongoDB sidecar:

# Follow logs (default 50 lines)
ujust fiftyone logs

# More lines (long form)
ujust fiftyone logs --lines=100

# More lines (short form)
ujust fiftyone logs -l 100

# Specific instance
ujust fiftyone logs -n 1 -l 100

Log output format:

[fiftyone-mongodb] 2024-01-09 10:00:01 MongoDB started
[fiftyone] 2024-01-09 10:00:02 Connecting to database...
[fiftyone] 2024-01-09 10:00:03 FiftyOne App ready on port 5151

Get URL

ujust fiftyone url
# Output: http://localhost:5151

# Specific instance
ujust fiftyone url --instance=2

Shell Access

# Interactive shell
ujust fiftyone shell

# Run specific command (use -- separator)
ujust fiftyone shell -- fiftyone --version
ujust fiftyone shell -- pip list

# Specific instance
ujust fiftyone shell --instance=2 -- python -c "import fiftyone as fo; print(fo.__version__)"

# Short form
ujust fiftyone shell -n 2 -- ls -la

Plugin Management

# List installed plugins
ujust fiftyone plugins -- list

# Install a plugin
ujust fiftyone plugins -- install <plugin-name>

# Update plugins
ujust fiftyone plugins -- update

Multi-Container Architecture

FiftyOne runs with a MongoDB sidecar:

+-------------------+        +-------------------+
|    FiftyOne       |        |     MongoDB       |
|   (fiftyone-1)    | -----> | (fiftyone-mongodb-1) |
|   Port 5151       |        |   Port 27017      |
+-------------------+        +-------------------+
         |                            |
         +---- bazzite-ai network ----+

Container Names: - fiftyone-{N} - Main FiftyOne container - fiftyone-mongodb-{N} - MongoDB sidecar

Lifecycle: - start starts MongoDB first, then FiftyOne - stop stops FiftyOne first, then MongoDB - logs shows interleaved output from both

Port Allocation

Instance FiftyOne Port MongoDB Port
1 5151 27017
2 5152 27018
N 5150+N 27016+N

GPU Support

FiftyOne supports GPU acceleration for ML model inference:

# Auto-detect GPU (default)
ujust fiftyone config

# Explicit NVIDIA (long form)
ujust fiftyone config --gpu-type=nvidia

# Explicit NVIDIA (short form)
ujust fiftyone config -g nvidia

Configuration Files

File Purpose Location
Instance config Per-instance settings ~/.config/fiftyone/instance-{N}.env
Quadlet unit (main) Service definition ~/.config/containers/systemd/fiftyone-{N}.container
Quadlet unit (MongoDB) Sidecar definition ~/.config/containers/systemd/fiftyone-mongodb-{N}.container

Common Workflows

Initial Setup

# 1. Configure FiftyOne with dataset directory
ujust fiftyone config --workspace-dir=/data/datasets

# 2. Start FiftyOne
ujust fiftyone start

# 3. Get URL
ujust fiftyone url

# 4. Open in browser
# http://localhost:5151

Dataset Analysis

# Start FiftyOne
ujust fiftyone start

# Open shell for interactive work
ujust fiftyone shell

# Inside container:
# import fiftyone as fo
# dataset = fo.load_dataset("my_dataset")
# session = fo.launch_app(dataset)

Network Access

# Configure for network access
ujust fiftyone config --bind=0.0.0.0

# Restart to apply
ujust fiftyone restart

# Access from other machines
# http://<hostname>:5151

Troubleshooting

FiftyOne Won't Start

Check:

ujust fiftyone status
ujust fiftyone logs --lines=50

Common causes:

  • Port 5151 already in use
  • MongoDB failed to start
  • GPU driver issues

Fix:

# Delete and reconfigure
ujust fiftyone delete
ujust fiftyone config --port=5152
ujust fiftyone start

MongoDB Connection Failed

Symptom: FiftyOne logs show "Connection refused" to MongoDB

Check:

# Check MongoDB container
podman ps | grep fiftyone-mongodb
ujust fiftyone logs | grep mongodb

Fix:

# Restart both containers
ujust fiftyone restart

Datasets Not Persisting

Symptom: Datasets disappear after restart

Check:

  • Verify config_dir is properly set
  • Check MongoDB volume mounts

Fix:

# Reconfigure with explicit config directory
ujust fiftyone config --config-dir=/data/fiftyone

Cross-References

  • Related Skills: jupyter (ML notebooks), ollama (LLM inference)
  • FiftyOne Docs: https://docs.voxel51.com/
  • GPU Setup: ujust config gpu setup

When to Use This Skill

Use when the user asks about:

  • "fiftyone", "dataset visualization", "dataset curation"
  • "ML datasets", "computer vision datasets"
  • "data labeling", "annotation tool"
  • "start fiftyone", "configure fiftyone"