fiftyone.core.session#

Module contents#

Session definitions for interacting with the FiftyOne App.

Copyright 2017-2026, Voxel51, Inc.
voxel51.com

Functions:

`close_app`()	Closes the FiftyOne App, if necessary.
`launch_app`([dataset, view, sample_id, ...])	Launches the FiftyOne App.

Classes:

Session([dataset, view, sample_id, ...])

Session that maintains a 1-1 shared state with the FiftyOne App.

fiftyone.core.session.close_app() → None#

Closes the FiftyOne App, if necessary.

If no App is currently open, this method has no effect.

fiftyone.core.session.launch_app(dataset: Dataset = None, view: DatasetView = None, sample_id: str = None, group_id: str = None, spaces: Space = None, color_scheme: ColorScheme = None, plots: PlotManager = None, port: int = None, address: str = None, remote: bool = False, browser: str = None, height: int = None, auto: bool = True, config: AppConfig = None) → Session#

Launches the FiftyOne App.

Note that only one App instance can be opened at a time. If this method is called when another App exists, the existing App will be closed.

Parameters:

dataset (None) – an optional fiftyone.core.dataset.Dataset or fiftyone.core.view.DatasetView to load
view (None) – an optional fiftyone.core.view.DatasetView to load
sample_id (None) – an optional fiftyone.core.sample.Sample ID to load in the modal
group_id (None) – an optional fiftyone.core.groups.Group ID to load in the modal
spaces (None) – an optional fiftyone.core.odm.workspace.Space instance defining a space configuration to load
color_scheme (None) – an optional fiftyone.core.odm.dataset.ColorScheme defining a custom color scheme to use
plots (None) – an optional fiftyone.core.plots.manager.PlotManager to connect to this session
port (None) – the port number to serve the App. If None, fiftyone.config.default_app_port is used
address (None) – the address to serve the App. If None, fiftyone.config.default_app_address is used
remote (False) – whether this is a remote session, and opening the App should not be attempted
browser (None) – an optional browser to use to open the App. If None, the default browser will be used. Refer to list of supported browsers at https://docs.python.org/3/library/webbrowser.html
height (None) – an optional height, in pixels, at which to render App instances in notebook cells. Only applicable in notebook contexts
auto (True) – whether to automatically show a new App window whenever the state of the session is updated. Only applicable in notebook contexts
config (None) – an optional fiftyone.core.config.AppConfig to control fine-grained default App settings

Returns:

a Session

class fiftyone.core.session.Session(dataset: Dataset | DatasetView = None, view: DatasetView = None, sample_id: str = None, group_id: str = None, spaces: Space = None, color_scheme: ColorScheme = None, plots: PlotManager = None, port: int = None, address: str = None, remote: bool = False, browser: str = None, height: int = None, auto: bool = True, config: AppConfig = None, view_name: str = None)#

Bases: object

Session that maintains a 1-1 shared state with the FiftyOne App.

Basic Usage

Use launch_app() to launch the App and retrieve its corresponding Session instance.
To open a dataset in the App, simply set the Session.dataset property of the session to your fiftyone.core.dataset.Dataset.
To load a specific view into your dataset, simply set the Session.view property of the session to your fiftyone.core.view.DatasetView.
To load a specific sample in the modal, simply set the Session.sample_id property of the session to the ID of the fiftyone.core.sample.Sample.
To load a specific group in the modal, simply set the Session.group_id property of the session to the ID of the fiftyone.core.groups.Group.
To attach/remove interactive plots, use the methods exposed on the Session.plots property of the session.
Use Session.refresh() to refresh the App if you update a dataset outside of the App
Use Session.selected to retrieve the IDs of the currently selected samples in the App.
Use Session.selected_labels to retrieve the IDs of the currently selected labels in the App.
In notebook contexts, use Session.freeze() to replace the App and any attached plots with static images.
Use Session.close() and Session.open() to temporarily close and reopen the App without creating a new Session instance.
Use close_app() to programmatically close the App and terminate the session.

Parameters:

dataset (None) – an optional fiftyone.core.dataset.Dataset or fiftyone.core.view.DatasetView to load
view (None) – an optional fiftyone.core.view.DatasetView to load
sample_id (None) – an optional fiftyone.core.sample.Sample ID to load in the modal
group_id (None) – an optional fiftyone.core.groups.Group ID to load in the modal
spaces (None) – an optional fiftyone.core.odm.workspace.Space instance defining a space configuration to load
color_scheme (None) – an optional fiftyone.core.odm.dataset.ColorScheme defining a custom color scheme to use
plots (None) – an optional fiftyone.core.plots.manager.PlotManager to connect to this session
port (None) – the port number to serve the App. If None, fiftyone.config.default_app_port is used
address (None) – the address to serve the App. If None, fiftyone.config.default_app_address is used
remote (False) – whether this is a remote session, and opening the App should not be attempted
browser (None) – an optional browser to use to open the App. If None, the default browser will be used. Refer to list of supported browsers at https://docs.python.org/3/library/webbrowser.html
height (None) – an optional height, in pixels, at which to render App instances in notebook cells. Only applicable in notebook contexts
auto (True) – whether to automatically show a new App window whenever the state of the session is updated. Only applicable in notebook contexts
config (None) – an optional fiftyone.core.config.AppConfig to control fine-grained default App settings

Attributes:

`auto`	The auto setting for the session.
`server_port`	The server port for the session.
`server_address`	The server address for the session, or None if not specified.
`remote`	Whether the session is remote.
`url`	The URL of the session.
`config`	The current `fiftyone.core.config.AppConfig`.
`group_id`	The current `fiftyone.core.groups.Group` ID in the modal, if any.
`sample_id`	The current `fiftyone.core.sample.Sample` ID in the modal, if any.
`spaces`	The layout state for the session.
`color_scheme`	The color scheme for the session.
`dataset`	The `fiftyone.core.dataset.Dataset` connected to the session.
`view`	The `fiftyone.core.view.DatasetView` connected to the session, or `None` if no view is connected.
`has_plots`	Whether this session has any attached plots.
`plots`	The `fiftyone.core.plots.manager.PlotManager` instance that manages plots attached to this session.
`selected`	A list of IDs of the currently selected samples in the App, if any.
`selected_samples`	A list of selected sample dicts, each with `id` and `type` (`"default"` or `"alt"`), where type corresponds to a key in `sample_selection_style`.
`sample_selection_style`	The current sample grid selection style config.
`label_selection_style`	The current label selection style config.
`selected_labels`	A list of labels currently selected in the App.
`selected_view`	A `fiftyone.core.view.DatasetView` containing the currently selected content in the App.

Methods:

`load_workspace`(workspace)	Loads the given saved workspace.
`clear_dataset`()	Clears the current `fiftyone.core.dataset.Dataset` from the session, if any.
`clear_view`()	Clears the current `fiftyone.core.view.DatasetView` from the session, if any.
`refresh`()	Refreshes the current App window.
`clear_selected`()	Clears the currently selected samples, if any.
`select_samples`([ids, tags])	Selects the specified samples in the current view in the App.
`set_sample_selection_style`([default, alt])	Sets the sample grid selection style in the App.
`clear_sample_selection_style`()	Clears the sample grid selection style, reverting to default checkmark.
`set_label_selection_style`([default, alt])	Sets the label selection style in the App.
`clear_label_selection_style`()	Clears the label selection style, reverting to default dashed.
`select_labels`([labels, ids, instance_ids, ...])	Selects the specified labels in the current view in the App.
`clear_selected_labels`()	Clears the currently selected labels, if any.
`tag_selected_samples`(tag)	Adds the tag to the currently selected samples, if necessary.
`untag_selected_samples`(tag)	Removes the tag from the currently selected samples, if necessary.
`tag_selected_labels`(tag)	Adds the tag to the currently selected labels, if necessary.
`untag_selected_labels`(tag)	Removes the tag from the currently selected labels, if necessary.
`summary`()	Returns a string summary of the session.
`open`()	Opens the App, if necessary.
`open_tab`()	Opens the App in a new tab of your browser.
`show`([height])	Opens the App in the output of the current notebook cell.
`no_show`()	Returns a context manager that temporarily prevents new App instances from being opened in the current notebook cell when methods are run that normally would show new App windows.
`wait`([wait])	Blocks execution until the App is closed by the user.
`close`()	Closes the session and terminates the App, if necessary.
`freeze`()	Screenshots the active App cell, replacing it with a static image.

property auto: bool#: The auto setting for the session.

property server_port: int#: The server port for the session.

property server_address: str#: The server address for the session, or None if not specified.

property remote: bool#: Whether the session is remote.

property url: str#: The URL of the session.

property config: AppConfig#

The current fiftyone.core.config.AppConfig.

For changes to a session’s config to take effect in the App, a call to Session.refresh() or another state-updating action such as session.view = my_view must occur.

Example usage:

import fiftyone as fo

dataset, session = fo.quickstart()

# change the show confidence setting and push the change to the App
session.config.show_confidence = False
session.refresh()

property group_id: str | None#: The current fiftyone.core.groups.Group ID in the modal, if any.

property sample_id: str | None#: The current fiftyone.core.sample.Sample ID in the modal, if any.

property spaces: Space#: The layout state for the session.

load_workspace(workspace: str) → None#

Loads the given saved workspace.

Parameters:: workspace – the name of a saved workspace

property color_scheme: ColorScheme#: The color scheme for the session.

property dataset: Dataset | None#: The fiftyone.core.dataset.Dataset connected to the session.

clear_dataset() → None#: Clears the current fiftyone.core.dataset.Dataset from the session, if any.

property view: DatasetView | None#: The fiftyone.core.view.DatasetView connected to the session, or None if no view is connected.

clear_view() → None#: Clears the current fiftyone.core.view.DatasetView from the session, if any.

property has_plots: bool#: Whether this session has any attached plots.

property plots: PlotManager | None#: The fiftyone.core.plots.manager.PlotManager instance that manages plots attached to this session.

refresh() → None#: Refreshes the current App window.

property selected: List[str]#: A list of IDs of the currently selected samples in the App, if any.

property selected_samples: List[Dict]#

A list of selected sample dicts, each with id and type ("default" or "alt"), where type corresponds to a key in sample_selection_style.

Despite its name, selected_samples represents whatever sample grid items are in the current view: samples in a standard dataset view, patches in a patches view, clips in a clips view, or frames in a frames view.

clear_selected() → None#: Clears the currently selected samples, if any.

select_samples(ids: str | Iterable | None = None, tags: str | Iterable[str] | None = None) → None#

Selects the specified samples in the current view in the App.

Despite its name, this applies to whatever sample grid items are in the current view: samples, patches, clips, or frames.

Parameters:

ids (None) – an ID or iterable of IDs to select. Items can be plain strings (all "default" type) or dicts of the form {"id": "...", "type": "default"|"alt"}, where type corresponds to a key in sample_selection_style.
tags (None) – a tag or iterable of tags to select

property sample_selection_style: Dict#

The current sample grid selection style config.

A dict with a default key and optional alt key specifying icon styles.

set_sample_selection_style(default: str = 'checkmark', alt: str = 'checkmark') → None#

Sets the sample grid selection style in the App.

Parameters:

default ("checkmark") – the default selection icon style. Supported values are "checkmark", "green-checkmark", "red-checkmark", "thumbsup", "thumbsdown", "pin", "star", "x", "bookmark"
alt ("checkmark") – the alt selection icon style

clear_sample_selection_style() → None#: Clears the sample grid selection style, reverting to default checkmark.

property label_selection_style: Dict#

The current label selection style config.

A dict with a default key and optional alt key specifying label selection visual styles.

set_label_selection_style(default: str = 'dashed', alt: str = 'dashed') → None#

Sets the label selection style in the App.

Parameters:

default ("dashed") – the default label selection style. Supported values are "dashed", "dashed-green", "dashed-red"
alt ("dashed") – the alt label selection style

clear_label_selection_style() → None#: Clears the label selection style, reverting to default dashed.

property selected_labels: List[dict]#

A list of labels currently selected in the App.

Items are dictionaries with the following keys:

label_id: the ID of the label
sample_id: the ID of the sample containing the label
instance_id: the instance ID of the label (optional)
field: the field name containing the label
frame_number: the frame number containing the label (only applicable to video samples)
type: the selection type ("default" or "alt"), which determines the visual style applied via label_selection_style

Selects the specified labels in the current view in the App.

This method uses the same interface as fiftyone.core.collections.SampleCollection.select_labels() to specify the labels to select.

Parameters:

labels (None) – a list of dicts specifying the labels to select
ids (None) – an ID or iterable of IDs of the labels to select
instance_ids (None) – an instance ID or iterable of instance IDs of the labels to select
tags (None) – a tag or iterable of tags of labels to select
fields (None) – a field or iterable of fields from which to select

clear_selected_labels() → None#: Clears the currently selected labels, if any.

tag_selected_samples(tag: str) → None#

Adds the tag to the currently selected samples, if necessary.

The currently selected labels are Session.selected.

Parameters:: tag – a tag

untag_selected_samples(tag: str) → None#

Removes the tag from the currently selected samples, if necessary.

The currently selected labels are Session.selected.

Parameters:: tag – a tag

tag_selected_labels(tag: str) → None#

Adds the tag to the currently selected labels, if necessary.

The currently selected labels are Session.selected_labels.

Parameters:: tag – a tag

untag_selected_labels(tag: str) → None#

Removes the tag from the currently selected labels, if necessary.

The currently selected labels are Session.selected_labels.

Parameters:: tag – a tag

property selected_view: DatasetView | None#

A fiftyone.core.view.DatasetView containing the currently selected content in the App.

The selected view is defined as follows:

If both samples and labels are selected, the view will contain only the selected_labels from within the selected samples
If samples are selected, the view will only contain the selected samples
If labels are selected, the view will only contain the selected_labels
If no samples or labels are selected, the view will be None

summary() → str#

Returns a string summary of the session.

Returns:: a string summary

open() → None#

Opens the App, if necessary.

The behavior of this method depends on your context:

Notebooks: calls Session.show() to open a new App window in the output of your current cell
Other (non-remote): opens the App in a new browser tab

open_tab() → None#

Opens the App in a new tab of your browser.

This method can be called from Jupyter notebooks to override the default location of the App.

show(height: int = None) → None#

Opens the App in the output of the current notebook cell.

This method has no effect in non-notebook contexts.

Parameters:: height (None) – a height, in pixels, for the App

no_show() → SetAttributes#

Returns a context manager that temporarily prevents new App instances from being opened in the current notebook cell when methods are run that normally would show new App windows.

This method has no effect in non-notebook contexts.

Examples:

import fiftyone as fo

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

# (new cell)

# Opens a new App instance
session.view = dataset.take(100)

# (new cell)

# Does not open a new App instance
with session.no_show():
    session.view = dataset.take(100)

Returns:: a context manager

wait(wait: float = 3) → None#

Blocks execution until the App is closed by the user.

All connected windows (tabs) must be closed before this method will unblock.

Parameters:: wait (3) – the number of seconds to wait for a new App connection before returning if all connections are lost. If negative, the process will wait forever, regardless of connections

close() → None#: Closes the session and terminates the App, if necessary.

freeze() → None#

Screenshots the active App cell, replacing it with a static image.

Only applicable to notebook contexts.