fiftyone Documentation

File: README.md Copy Chapter

👋 hey there!

We created FiftyOne to supercharge your visual AI
development by enabling you to visualize and label your data, evaluate your
models, and maximize data and model quality more efficiently than ever before
🤝

If you're looking to scale to production-grade, collaborative, cloud-native
enterprise workloads, check out
FiftyOne Enterprise 🚀

  installation   💻 Copy Chapter

As simple as:

pip install fiftyone

More details

Installation options Copy Section

FiftyOne supports Python 3.10 - 3.14.

For most users, we recommend installing the latest release version of FiftyOne
via pip as shown above.

If you want to contribute to FiftyOne or install the latest development
version, then you can also perform a source install.

See the prerequisites section for system-specific setup
information.

We strongly recommend that you install FiftyOne in a
virtual environment to
maintain a clean workspace.

Consult the
installation guide for
troubleshooting and other information about getting up-and-running with
FiftyOne.

Install from source

Source installations Copy Section

Follow the instructions below to install FiftyOne from source and build the
App.

You'll need the following tools installed:

• Python (3.10 - 3.14)
• Node.js - on Linux, we recommend using
  nvm to install an up-to-date version.
• Yarn - once Node.js is installed, you can
  enable Yarn via
  corepack enable

We strongly recommend that you install FiftyOne in a
virtual environment to
maintain a clean workspace.

If you are working in Google Colab,
skip to here.

First, clone the repository:

git clone https://github.com/voxel51/fiftyone
cd fiftyone

Then run the install script:

# Mac or Linux
bash install.sh

# Windows
.\install.bat

If you run into issues importing FiftyOne, you may need to add the path to the
cloned repository to your PYTHONPATH:

export PYTHONPATH=$PYTHONPATH:/path/to/fiftyone

Note that the install script adds to your nvm settings in your ~/.bashrc or
~/.bash_profile, which is needed for installing and building the App.

Upgrading your source installation Copy Section

To upgrade an existing source installation to the bleeding edge, simply pull
the latest develop branch and rerun the install script:

git checkout develop
git pull

# Mac or Linux
bash install.sh

# Windows
.\install.bat

Rebuilding the App Copy Section

When you pull in new changes to the App, you will need to rebuild it, which you
can do either by rerunning the install script or just running yarn build in
the ./app directory.

Developer installation Copy Section

If you would like to
contribute to FiftyOne,
you should perform a developer installation using the -d flag of the install
script:

# Mac or Linux
bash install.sh -d

# Windows
.\install.bat -d

Although not required, developers typically prefer to configure their FiftyOne
installation to connect to a self-installed and managed instance of MongoDB,
which you can do by following
these simple steps.

Source installs in Google Colab Copy Section

You can install from source in
Google Colab by running the following in a
cell and then restarting the runtime:

%%shell

git clone --depth 1 https://github.com/voxel51/fiftyone.git
cd fiftyone

# Mac or Linux
bash install.sh

# Windows
.\install.bat

Generating documentation Copy Section

See the
docs guide
for information on building and contributing to the documentation.

Uninstallation Copy Section

You can uninstall FiftyOne as follows:

pip uninstall fiftyone fiftyone-brain fiftyone-db

Prerequisites for beginners

System-specific setup Copy Section

Follow the instructions for your operating system or environment to perform
basic system setup before installing FiftyOne.

If you're an experienced developer, you've likely already done this.

Linux

1. Install Python and other dependencies

These steps work on a clean install of Ubuntu Desktop 24.04, and should also
work on Ubuntu 24.04 and 22.04, and on Ubuntu Server:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install python3-venv python3-dev build-essential git-all libgl1-mesa-dev

• On Linux, you will need at least the openssl and libcurl packages
• On Debian-based distributions, you will need to install libcurl4 or
  libcurl3 instead of libcurl, depending on the age of your distribution

# Ubuntu
sudo apt install libcurl4 openssl

# Fedora
sudo dnf install libcurl openssl

2. Create and activate a virtual environment

python3 -m venv fiftyone_env
source fiftyone_env/bin/activate

3. Install FFmpeg (optional)

If you plan to work with video datasets, you'll need to install
FFmpeg:

sudo apt-get install ffmpeg

MacOS

1. Install Xcode Command Line Tools

xcode-select --install

2. Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After running the above command, follow the instructions in your terminal to
complete the Homebrew installation.

3. Install Python

brew install [email protected]
brew install protobuf

4. Create and activate a virtual environment

python3 -m venv fiftyone_env
source fiftyone_env/bin/activate

5. Install FFmpeg (optional)

If you plan to work with video datasets, you'll need to install
FFmpeg:

brew install ffmpeg

Windows

1. Install Python

⚠️ The version of Python that is available in the Microsoft Store is not
recommended ⚠️

Download a Python 3.10 - 3.14 installer from
python.org. Make sure to pick a 64-bit
version. For example, this
Python 3.10.11 installer.

Double-click on the installer to run it, and follow the steps in the installer.

• Check the box to add Python to your PATH
• At the end of the installer, there is an option to disable the PATH length
  limit. It is recommended to click this

2. Install Microsoft Visual C++

Download
Microsoft Visual C++ Redistributable.
Double-click on the installer to run it, and follow the steps in the installer.

3. Install Git

Download Git from this link. Double-click
on the installer to run it, and follow the steps in the installer.

4. Create and activate a virtual environment

• Press Win + R. type cmd, and press Enter. Alternatively, search
  Command Prompt in the Start Menu.
• Navigate to your project. cd C:\path\to\your\project
• Create the environment python -m venv fiftyone_env
• Activate the environment typing this in the command line window
  fiftyone_env\Scripts\activate
• After activation, your command prompt should change and show the name of the
  virtual environment (fiftyone_env) C:\path\to\your\project

5. Install FFmpeg (optional)

If you plan to work with video datasets, you'll need to install
FFmpeg.

Download an FFmpeg binary from here. Add
FFmpeg's path (e.g., C:\ffmpeg\bin) to your PATH environmental variable.

Docker

Refer to
these instructions
to see how to build and run Docker images containing release or source builds
of FiftyOne.

  quickstart   🚀 Copy Chapter

Dive right into FiftyOne by opening a Python shell and running the snippet
below, which downloads a
small dataset
and launches the FiftyOne App
so you can explore it:

import fiftyone as fo
import fiftyone.zoo as foz

dataset = foz.load_zoo_dataset("quickstart")
session = fo.launch_app(dataset)

Then check out
this Colab notebook
to see some common workflows on the quickstart dataset.

Note that if you are running the above code in a script, you must include
session.wait() to block execution until you close the App. See
this page
for more information.

  key features   🔑 Copy Chapter

• Native Annotation:
  Create and edit 2D and 3D labels directly in the App or integrate with your
  favorite annotation tools — then curate, QA, and iterate, all in one
  platform.

https://github.com/user-attachments/assets/b06bcdac-d64f-4465-8668-12007dc0eeaa

• Visualize Complex Datasets:
  Easily explore images, videos, and associated labels in a powerful visual
  interface.

https://github.com/user-attachments/assets/9dc2db88-967d-43fa-bda0-85e4d5ab6a7a

• Explore Embeddings:
  Select points of interest and view the corresponding samples/labels.

https://github.com/user-attachments/assets/246faeb7-dcab-4e01-9357-e50f6b106da7

• Analyze and Improve Models:
  Evaluate model performance, identify failure modes, and fine-tune your
  models.

https://github.com/user-attachments/assets/8c32d6c4-51e7-4fea-9a3c-2ffd9690f5d6

• Advanced Data Curation: Quickly
  find and fix data issues, annotation errors, and edge cases.

https://github.com/user-attachments/assets/24fa1960-c2dd-46ae-ae5f-d58b3b84cfe4

• Rich Integrations:
  Works with popular deep learning libraries like PyTorch, Hugging Face,
  Ultralytics, and more.

https://github.com/user-attachments/assets/de5f25e1-a967-4362-9e04-616449e745e5

• Open and Extensible:
  Customize and extend FiftyOne to fit your specific needs.

https://github.com/user-attachments/assets/c7ed496d-0cf7-45d6-9853-e349f1abd6f8

  documentation   🪪 Copy Chapter

Check out these resources to get up and running with FiftyOne:

Full documentation is available at fiftyone.ai.

  additional resources   🚁 Copy Chapter

  FiftyOne Enterprise   🏎️ Copy Chapter

Want to securely collaborate on billions of samples in the cloud and connect to
your compute resources to automate your workflows? Check out
FiftyOne Enterprise.

  faq & troubleshooting   ⛓️‍💥 Copy Chapter

Refer to our
common issues
page to troubleshoot installation issues. If you're still stuck, check our
frequently asked questions page for
more answers.

If you encounter an issue that the above resources don't help you resolve, feel
free to open an issue on GitHub
or contact us on Discord.

  join our community   🤝 Copy Chapter

Connect with us through your preferred channels:

🎊 Share how FiftyOne makes your visual AI projects a reality on social media
and tag us with @Voxel51 and #FiftyOne 🎊

  contributors   🧡 Copy Chapter

FiftyOne and FiftyOne Brain are
open source and community contributions are welcome! Check out the
contribution guide
to learn how to get involved.

Special thanks to these amazing people for contributing to FiftyOne!

  citation   📖 Copy Chapter

If you use FiftyOne in your research, feel free to cite the project (but only
if you love it 😊):

@article{moore2020fiftyone,
  title={FiftyOne},
  author={Moore, B. E. and Corso, J. J.},
  journal={GitHub. Note: https://github.com/voxel51/fiftyone},
  year={2020}
}

File: docs/README.md Copy Chapter

FiftyOne Documentation

The official FiftyOne documentation, available at
fiftyone.ai.

FiftyOne uses Sphinx and
Sphinx-Napoleon to
generate its documentation and API reference from source.

Prerequisites Copy Chapter

Before building the docs locally, ensure you have:

• Python 3.12 installed and a
  virtual environment
  created specifically for documentation.

  Note: Do NOT use the same environment where you ran install.sh
  with the -d (dev mode) flag, as docs dependencies may conflict with test
  dependencies.

• pandoc installed.

• A Unix-like shell environment to execute bash commands.

Setup Copy Chapter

To build the documentation locally, follow these steps:

1. Install FiftyOne:

   shell Copy

   cd ..
   bash install.sh

2. Install documentation-specific requirements:

   shell Copy

   pip install -r requirements/docs.txt

3. To use the fiftyone repository to autogenerate docs, you need to add it to
   your PYTHONPATH:

   shell Copy

   export PYTHONPATH=$PYTHONPATH:/path/to/fiftyone

Tip: to avoid running this every time you build the docs, add the previous
line to your ~/.bashrc, ~/.zshrc, or the appropriate shell profile for your
environment.

Building Copy Chapter

You can build the docs from source by running the generate_docs.bash script
in this folder:

bash docs/generate_docs.bash

A couple notable flags are supported:

• -c performs a clean build by removing the docs/build folder beforehand.
  This is sometimes necessary to force updates, e.g. if you have edited a
  template and want to see how it affects pages whose source files haven't
  changed
• -s will update static files only, i.e. custom.css and custom.js
  mentioned below
• -f will perform a fast build, i.e. zoo and plugin docs will be skipped

Previewing a single page Copy Chapter

To preview a single page with full styling without running a full build:

bash docs/preview_page.bash user_guide/using_datasets.rst

This supports RST and Jupyter notebook files and opens the result in your
browser. No prior build is required.

Contributing Copy Chapter

Main Content Copy Section

The main content is located in the docs/source folder. The files are written
in Sphinx RST format.

The API documentation is automatically generated from the Python source code,
whose docstrings are written in
Sphinx-Napoleon format.

Check out the existing patterns in the source files and you'll catch on.

FiftyOne Brain Copy Section

For Voxel51 developers who are working with a source install of the FiftyOne
Brain: the build script will automatically use your source install!

Teams SDK Copy Section

Voxel51 developers can include Teams SDK-related components in their local docs
build by including the -t flag:

bash docs/generate_docs.bash -t /path/to/fiftyone-teams

Style Guide Copy Section

All documentation, including RST and all code samples embedded in it, must
follow our style guide.

Note that pre-commit hooks will automatically enforce the whitespace-related
components of our style when you commit changes.

Themes Copy Section

This extends the theme pydata_sphinx_theme. However, you should prefer to
make changes in the following locations instead of the theme itself whenever
possible:

• docs/source/_static contains custom.css and custom.js files, where any
  CSS overrides or custom JS should be added
• docs/source/_templates contains HTML files (Jinja2 templates) that override
  theme templates of the same name. These should extend the theme templates -
  see the existing templates for how to do this. If you need to override part
  of the theme template that isn't conveniently marked as a block (and isn't a
  separate file that you can override), our convention is to add a block
  prefixed with custom_ to the theme template, then override that block
  locally

Compile CSS Copy Section

To compile Sass styles into CSS for the documentation:

make css

This command compiles the Sass files located in docs/source/assets/styles/
and outputs the compiled CSS to docs/source/_static/custom.css.