# Configuring FiftyOne
Available in:
Open SourceEnterprise
FiftyOne can be configured in various ways. This guide covers the various
options that exist, how to view your current config, and how to customize your
config as desired.
## Configuration options
FiftyOne supports the configuration options described below:
| Config field | Environment variable | Default value | Description |
|----------------------------------------|-------------------------------------------------|-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `database_admin` | `FIFTYONE_DATABASE_ADMIN` | `True` | Whether the client is allowed to trigger database migrations. See
[this section](#database-migrations) for more information. |
| `database_compressor` | `FIFTYONE_DATABASE_COMPRESSOR` | `None` | Optional [MongoDB network compression](#mongodb-network-compression) to use. The
supported values are `None`, `zstd`, `zlib`, or `snappy`. |
| `database_dir` | `FIFTYONE_DATABASE_DIR` | `~/.fiftyone/var/lib/mongo` | The directory in which to store FiftyOne’s backing database. Only applicable if
`database_uri` is not defined. |
| `database_name` | `FIFTYONE_DATABASE_NAME` | `fiftyone` | A name to use for FiftyOne’s backing database in your MongoDB instance. The database
is automatically created if necessary. |
| `database_uri` | `FIFTYONE_DATABASE_URI` | `None` | A [MongoDB URI](https://docs.mongodb.com/manual/reference/connection-string/) to
specifying a custom MongoDB database to which to connect. See
[this section](#configuring-mongodb-connection) for more information. |
| `database_validation` | `FIFTYONE_DATABASE_VALIDATION` | `True` | Whether to validate the compatibility of database before connecting to it. See
[this section](#configuring-mongodb-connection) for more information. |
| `dataset_zoo_dir` | `FIFTYONE_DATASET_ZOO_DIR` | `~/fiftyone` | The default directory in which to store datasets that are downloaded from the
[FiftyOne Dataset Zoo](../dataset_zoo/index.md#dataset-zoo). |
| `dataset_zoo_manifest_paths` | `FIFTYONE_DATASET_ZOO_MANIFEST_PATHS` | `None` | A list of manifest JSON files specifying additional zoo datasets. See
[adding datasets to the zoo](../dataset_zoo/api.md#dataset-zoo-add) for more information. |
| `default_dataset_dir` | `FIFTYONE_DEFAULT_DATASET_DIR` | `~/fiftyone` | The default directory to use when performing FiftyOne operations that
require writing dataset contents to disk, such as ingesting datasets via
[`ingest_labeled_images()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.ingest_labeled_images). |
| `default_ml_backend` | `FIFTYONE_DEFAULT_ML_BACKEND` | `torch` | The default ML backend to use when performing operations such as
downloading datasets from the FiftyOne Dataset Zoo that support multiple ML
backends. Supported values are `torch` and `tensorflow`. By default,
`torch` is used if [PyTorch](https://pytorch.org) is installed in your
Python environment, and `tensorflow` is used if
[TensorFlow](http://tensorflow.org) is installed. If no supported backend
is detected, this defaults to `None`, and any operation that requires an
installed ML backend will raise an informative error message if invoked in
this state. |
| `default_batch_size` | `FIFTYONE_DEFAULT_BATCH_SIZE` | `None` | A default batch size to use when [applying models to datasets](../model_zoo/api.md#model-zoo-apply). |
| `default_batcher` | `FIFTYONE_DEFAULT_BATCHER` | `latency` | Batching implementation to use in some batched database operations such as
[`add_samples()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.add_samples),
[`set_values()`](../api/fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection.set_values), and
[`save_context()`](../api/fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection.save_context).
Supported values are `latency`, `size`, and `static`.
`latency` is the default, which uses a dynamic batch size to achieve a target latency
of `batcher_target_latency` between calls. The default changes to `size` for the
FiftyOne Enterprise SDK in [API connection mode](../enterprise/api_connection.md#enterprise-api-connection),
which targets a size of `batcher_target_size_bytes` for each call. `static` uses a
fixed batch size of `batcher_static_size`. |
| `batcher_static_size` | `FIFTYONE_BATCHER_STATIC_SIZE` | `100` | Fixed size of batches. Only used when `default_batcher` is `static`. |
| `batcher_target_size_bytes` | `FIFTYONE_BATCHER_TARGET_SIZE_BYTES` | `2 ** 20` | Target content size of batches, in bytes. Only used when `default_batcher` is `size`. |
| `batcher_target_latency` | `FIFTYONE_BATCHER_TARGET_LATENCY` | `0.2` | Target latency between batches, in seconds. Only used when `default_batcher` is
`latency`. |
| `default_sequence_idx` | `FIFTYONE_DEFAULT_SEQUENCE_IDX` | `%06d` | The default numeric string pattern to use when writing sequential lists of
files. |
| `default_image_ext` | `FIFTYONE_DEFAULT_IMAGE_EXT` | `.jpg` | The default image format to use when writing images to disk. |
| `default_video_ext` | `FIFTYONE_DEFAULT_VIDEO_EXT` | `.mp4` | The default video format to use when writing videos to disk. |
| `default_app_port` | `FIFTYONE_DEFAULT_APP_PORT` | `5151` | The default port to use to serve the [FiftyOne App](app.md#fiftyone-app). |
| `default_app_address` | `FIFTYONE_DEFAULT_APP_ADDRESS` | `localhost` | The default address to use to serve the [FiftyOne App](app.md#fiftyone-app). This may
be either an IP address or hostname. If it’s a hostname, the App will listen to all
IP addresses associated with the name. The default is `localhost`, which means the App
will only listen on the local interface. See [this page](../installation/environments.md#restricting-app-address)
for more information. |
| `allowed_origins` | `FIFTYONE_ALLOWED_ORIGINS` | `None` | Comma-separated list of origins (e.g. `https://app.example.com,http://localhost:3000`)
that may make cross-origin requests to the App server. Empty (default) is same-origin
only, which covers local desktop usage and the supported notebook integrations, since
each serves the App through a same-origin proxy or iframe. Set this only for
cross-origin embeds. The literal value `*` restores the legacy wildcard. Please be
aware of the security implications of setting this to `*`. |
| `delegated_operation_monitor_interval` | `FIFTYONE_DELEGATED_OPERATION_MONITOR_INTERVAL` | `60` | Interval to monitor delegated operation (DO) state in seconds. If the DO has failed we
will terminate execution, otherwise we will update the DO to confirm the worker is
still alive and executing. |
| `do_not_track` | `FIFTYONE_DO_NOT_TRACK` | `False` | Controls whether UUID based import and App usage events are tracked. |
| `logging_destination` | `FIFTYONE_LOGGING_DESTINATION` | `stdout` | Controls FiftyOne’s package-wide logging destination. Can be either `stdout` to send
all logs to stdout, or `stdout,stderr` to log errors to stderr and everything below
an error to stdout. |
| `logging_format` | `FIFTYONE_LOGGING_FORMAT` | `text` | Controls FiftyOne’s package-wide logging format. Can be either `text` or `json`. |
| `logging_level` | `FIFTYONE_LOGGING_LEVEL` | `INFO` | Controls FiftyOne’s package-wide logging level. Can be any valid `logging` level as
a string: `DEBUG, INFO, WARNING, ERROR, CRITICAL`. |
| `default_parallelization_method` | `FIFTYONE_DEFAULT_PARALLELIZATION_METHOD` | `None` | The default parallelization method to use when methods that support parallelism are
invoked. The supported values are `process` and `thread`. By default, the `process`
backend is used whenever the execution environment supports it. |
| `default_thread_pool_workers` | `FIFTYONE_DEFAULT_THREAD_POOL_WORKERS` | `None` | The default number of worker threads to use when methods that support parallelism are
invoked with the `thread` backend. |
| `default_process_pool_workers` | `FIFTYONE_DEFAULT_PROCESS_POOL_WORKERS` | `None` | The default number of worker threads to use when methods that support parallelism are
invoked with the `process` backend. |
| `max_thread_pool_workers` | `FIFTYONE_MAX_THREAD_POOL_WORKERS` | `None` | A maximum number of workers to allow when creating thread pools. |
| `max_process_pool_workers` | `FIFTYONE_MAX_PROCESS_POOL_WORKERS` | `None` | A maximum number of workers to allow when creating process pools. |
| `model_zoo_dir` | `FIFTYONE_MODEL_ZOO_DIR` | `~/fiftyone/__models__` | The default directory in which to store models that are downloaded from the
[FiftyOne Model Zoo](../model_zoo/index.md#model-zoo). |
| `model_zoo_manifest_paths` | `FIFTYONE_MODEL_ZOO_MANIFEST_PATHS` | `None` | A list of manifest JSON files specifying additional zoo models. See
[adding models to the zoo](../model_zoo/api.md#model-zoo-add) for more information. |
| `module_path` | `FIFTYONE_MODULE_PATH` | `None` | A list of modules that should be automatically imported whenever FiftyOne is imported.
See [this page](using_datasets.md#custom-embedded-documents) for an example usage. |
| `operator_timeout` | `FIFTYONE_OPERATOR_TIMEOUT` | `600` | The timeout for execution of an operator. See [this page](../plugins/overview.md#fiftyone-plugins) for
more information. |
| `allow_legacy_orchestrators` | `FIFTYONE_ALLOW_LEGACY_ORCHESTRATORS` | `False` | Whether to allow delegated operations to be scheduled locally.
See [this page](../plugins/using_plugins.md#delegated-orchestrator-open-source) for more information. |
| `plugins_dir` | `FIFTYONE_PLUGINS_DIR` | `None` | A directory containing custom App plugins. See [this page](../plugins/overview.md#fiftyone-plugins) for
more information. |
| `plugins_cache_enabled` | `FIFTYONE_PLUGINS_CACHE_ENABLED` | `False` | When set to `True` plugins will be cached until their directory’s `mtime` changes.
This is intended to be used in production. |
| `show_progress_bars` | `FIFTYONE_SHOW_PROGRESS_BARS` | `True` | Controls whether progress bars are printed to the terminal when performing
operations such reading/writing large datasets or activating FiftyOne
Brain methods on datasets. |
| `singleton_cache` | `FIFTYONE_SINGLETON_CACHE` | `True` | Whether to treat [`Dataset`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset),
[`Sample`](../api/fiftyone.core.sample.md#fiftyone.core.sample.Sample), and
[`Frame`](../api/fiftyone.core.frame.md#fiftyone.core.frame.Frame) instances as singletons. |
| `timezone` | `FIFTYONE_TIMEZONE` | `None` | An optional timezone string. If provided, all datetimes read from FiftyOne datasets
will be expressed in this timezone. See [this section](#configuring-timezone) for
more information. |
## Viewing your config
You can print your current FiftyOne config at any time via the Python library
and the CLI:
Python
CLI
```python
import fiftyone as fo
# Print your current config
print(fo.config)
# Print a specific config field
print(fo.config.default_ml_backend)
```
```text
{
"batcher_static_size": 100,
"batcher_target_latency": 0.2,
"batcher_target_size_bytes": 1048576,
"database_admin": true,
"database_dir": "~/.fiftyone/var/lib/mongo",
"database_name": "fiftyone",
"database_uri": null,
"database_validation": true,
"dataset_zoo_dir": "~/fiftyone",
"dataset_zoo_manifest_paths": null,
"allowed_origins": null,
"default_app_address": null,
"default_app_port": 5151,
"default_batch_size": null,
"default_batcher": "latency",
"default_dataset_dir": "~/fiftyone",
"default_image_ext": ".jpg",
"default_ml_backend": "torch",
"default_parallelization_method": null,
"default_process_pool_workers": null,
"default_sequence_idx": "%06d",
"default_thread_pool_workers": null,
"default_video_ext": ".mp4",
"do_not_track": false,
"logging_level": "INFO",
"max_process_pool_workers": null,
"max_thread_pool_workers": null,
"model_zoo_dir": "~/fiftyone/__models__",
"model_zoo_manifest_paths": null,
"module_path": null,
"operator_timeout": 600,
"allow_legacy_orchestrators": false,
"plugins_cache_enabled": false,
"plugins_dir": null,
"requirement_error_level": 0,
"show_progress_bars": true,
"singleton_cache": true,
"timezone": null
}
torch
```
```shell
# Print your current config
fiftyone config
# Print a specific config field
fiftyone config default_ml_backend
```
```text
{
"batcher_static_size": 100,
"batcher_target_latency": 0.2,
"batcher_target_size_bytes": 1048576,
"database_admin": true,
"database_dir": "~/.fiftyone/var/lib/mongo",
"database_name": "fiftyone",
"database_uri": null,
"database_validation": true,
"dataset_zoo_dir": "~/fiftyone",
"dataset_zoo_manifest_paths": null,
"allowed_origins": null,
"default_app_address": null,
"default_app_port": 5151,
"default_batch_size": null,
"default_batcher": "latency",
"default_dataset_dir": "~/fiftyone",
"default_image_ext": ".jpg",
"default_ml_backend": "torch",
"default_parallelization_method": null,
"default_process_pool_workers": null,
"default_sequence_idx": "%06d",
"default_thread_pool_workers": null,
"default_video_ext": ".mp4",
"do_not_track": false,
"logging_level": "INFO",
"max_process_pool_workers": null,
"max_thread_pool_workers": null,
"model_zoo_dir": "~/fiftyone/__models__",
"model_zoo_manifest_paths": null,
"module_path": null,
"operator_timeout": 600,
"allow_legacy_orchestrators": false,
"plugins_cache_enabled": false,
"plugins_dir": null,
"requirement_error_level": 0,
"show_progress_bars": true,
"singleton_cache": true,
"timezone": null
}
torch
```
#### NOTE
If you have customized your FiftyOne config via any of the methods
described below, printing your config is a convenient way to ensure that
the changes you made have taken effect as you expected.
## Modifying your config
You can modify your FiftyOne config in a variety of ways. The following
sections describe these options in detail.
### Order of precedence
The following order of precedence is used to assign values to your FiftyOne
config settings at runtime:
1. Config changes applied at runtime by directly editing `fiftyone.config`
2. `FIFTYONE_XXX` environment variables
3. Settings in your JSON config (`~/.fiftyone/config.json`)
4. The default config values
### Editing your JSON config
You can permanently customize your FiftyOne config by creating a
`~/.fiftyone/config.json` file on your machine. The JSON file may contain any
desired subset of config fields that you wish to customize.
For example, a valid config JSON file is:
```json
{
"default_ml_backend": "tensorflow",
"show_progress_bars": true
}
```
When `fiftyone` is imported, any options from your JSON config are applied,
as per the order of precedence described above.
#### NOTE
You can customize the location from which your JSON config is read by
setting the `FIFTYONE_CONFIG_PATH` environment variable.
### Setting environment variables
FiftyOne config settings may be customized on a per-session basis by setting
the `FIFTYONE_XXX` environment variable(s) for the desired config settings.
When `fiftyone` is imported, all config environment variables are applied, as
per the order of precedence described above.
For example, you can customize your FiftyOne config in a Terminal session by
issuing the following commands prior to launching your Python interpreter:
```shell
export FIFTYONE_DEFAULT_ML_BACKEND=tensorflow
export FIFTYONE_SHOW_PROGRESS_BARS=true
```
### Modifying your config in code
You can dynamically modify your FiftyOne config at runtime by editing the
`fiftyone.config` object.
Any changes to your FiftyOne config applied via this manner will immediately
take effect for all subsequent calls to `fiftyone.config` during your current
session.
```python
import fiftyone as fo
fo.config.default_ml_backend = "tensorflow"
fo.config.show_progress_bars = True
```
## Configuring a MongoDB connection
Available in:
Open SourceEnterprise
By default, FiftyOne is installed with its own MongoDB database distribution.
This database is managed by FiftyOne automatically as a service that runs
whenever at least one FiftyOne Python client is alive.
Alternatively, you can configure FiftyOne to connect to your own self-managed
MongoDB instance. To do so, simply set the `database_uri` property of your
FiftyOne config to any valid
[MongoDB connection string URI](https://docs.mongodb.com/manual/reference/connection-string/).
You can achieve this by adding the following entry to your
`~/.fiftyone/config.json` file:
```json
{
"database_uri": "mongodb://[username:password@]host[:port]"
}
```
or you can set the following environment variable:
```shell
export FIFTYONE_DATABASE_URI=mongodb://[username:password@]host[:port]
```
If you are running MongoDB with authentication enabled (the `--auth` flag),
FiftyOne must connect as a root user.
You can create a root user with the Mongo shell as follows:
```shell
mongo --shell
> use admin
> db.createUser({user: "username", pwd: passwordPrompt(), roles: ["root"]})
```
You must also add `?authSource=admin` to your database URI:
```text
mongodb://[username:password@]host[:port]/?authSource=admin
```
### MongoDB network compression
Available in:
Open SourceEnterprise
You can optionally configure
[MongoDB network compression](https://www.mongodb.com/developer/products/mongodb/mongodb-network-compression)
via the `database_compressor` config setting.
By default, compression is disabled, but enabling it can give a significant
performance boost in suboptimal network environments.
You can achieve this by adding the following entry to your
`~/.fiftyone/config.json` file:
```json
{
"database_compressor": "zstd"
}
```
or you can set the following environment variable:
```shell
export FIFTYONE_DATABASE_COMPRESSOR=zstd
```
The supported values are `zstd`, `zlib`, and `snappy`.
When network compression makes sense, we recommend `zstd` as the preferred
compressor based on our benchmarking results, but any compressor supported by
your version of MongoDB will work, provided you’ve installed the required
python package.
### Using a different MongoDB version
FiftyOne is designed for **MongoDB v6.0 or later**.
If you wish to connect FiftyOne to a MongoDB database whose version is not
explicitly supported, you will also need to set the `database_validation`
property of your FiftyOne config to `False` to suppress a runtime error that
will otherwise occur.
You can achieve this by adding the following entry to your
`~/.fiftyone/config.json` file:
```json
{
"database_validation": false
}
```
or you can set the following environment variable:
```shell
export FIFTYONE_DATABASE_VALIDATION=false
```
### Controlling database migrations
If you are working with a shared MongoDB database, you can use
[database admin privileges](#database-migrations) to control which clients
are allowed to migrate the shared database.
### Example custom database usage
In order to use a custom MongoDB database with FiftyOne, you must manually
start the database before importing FiftyOne. MongoDB provides
[a variety of options](https://docs.mongodb.com/manual/tutorial/manage-mongodb-processes)
for this, including running the database as a daemon automatically.
In the simplest case, you can just run `mongod` in one shell:
```shell
mkdir -p /path/for/db
mongod --dbpath /path/for/db
```
Then, in another shell, configure the database URI and launch FiftyOne:
```shell
export FIFTYONE_DATABASE_URI=mongodb://localhost
```
```python
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart")
session = fo.launch_app(dataset)
```
## Database migrations
Available in:
Open SourceEnterprise
New FiftyOne versions occasionally introduce data model changes that require
database migrations when you [upgrade](../installation/index.md#upgrading-fiftyone) or
[downgrade](../installation/index.md#downgrading-fiftyone).
By default, database upgrades happen automatically in two steps:
- **Database**: when you import FiftyOne for the first time using a newer
version of the Python package, the database’s version is automatically
updated to match your client version
- **Datasets** are lazily migrated to the current database version on a
per-dataset basis whenever you load the dataset for the first time using a
newer version of the FiftyOne package
Database downgrades must be manually performed. See
[this page](../installation/index.md#downgrading-fiftyone) for instructions.
You can use the [fiftyone migrate](../cli/index.md#cli-fiftyone-migrate) command to view
the current versions of your client, database, and datasets:
```shell
# View your client, database, and dataset versions
fiftyone migrate --info
```
```text
Client version: 0.16.6
Compatible versions: >=0.16.3,<0.17
Database version: 0.16.6
dataset version
--------------------------- ---------
bdd100k-validation 0.16.5
quickstart 0.16.5
...
```
### Restricting migrations
You can use the `database_admin` config setting to control whether a client is
allowed to upgrade/downgrade your FiftyOne database. The default is `True`,
which means that upgrades are automatically performed when you connect to your
database with newer Python client versions.
If you set `database_admin` to `False`, your client will **never** cause the
database to be migrated to a new version. Instead, you’ll see the following
behavior:
- If your client is compatible with the current database version, you will be
allowed to connect to the database and use FiftyOne
- If your client is not compatible with the current database version, you
will see an informative error message when you import the library
You can restrict migrations by adding the following entry to your
`~/.fiftyone/config.json` file:
```json
{
"database_admin": false
}
```
or by setting the following environment variable:
```shell
export FIFTYONE_DATABASE_ADMIN=false
```
#### NOTE
A common pattern when working with
[custom/shared MongoDB databases](#configuring-mongodb-connection) is
to adopt a convention that all non-administrators set their
`database_admin` config setting to `False` to ensure that they cannot
trigger automatic database upgrades by connecting to the database with
newer Python client versions.
### Coordinating a migration
If you are working in an environment where multiple services are connecting to
your MongoDB database at any given time, use this strategy to upgrade your
deployment:
1. Ensure that all clients are running without database admin privileges,
e.g., by adding this to their `~/.fiftyone/config.json`:
```json
{
"database_admin": false
}
```
1. Perform a test upgrade of one client and ensure that it is compatible with
your current database version:
```shell
# In a test environment
pip install --upgrade fiftyone
# View client's compatibility info
fiftyone migrate --info
```
```python
import fiftyone as fo
# Convince yourself that the new client can load a dataset
dataset = fo.load_dataset(...)
```
1. Now upgrade the client version used by all services:
```shell
# In all client environments
pip install --upgrade fiftyone
```
1. Once all services are running the new client version, upgrade the database
with admin privileges:
```shell
export FIFTYONE_DATABASE_ADMIN=true
pip install --upgrade fiftyone
fiftyone migrate --all
```
#### NOTE
Newly created datasets will always bear the
[`version`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.version) of the Python
client that created them, which may differ from your database’s version
if you are undergoing a migration.
If the new client’s version is not in the compatibility range for the old
clients that are still in use, the old clients will not be able to load
the new datasets.
Therefore, it is recommended to upgrade all clients as soon as possible!
## Configuring a timezone
By default, FiftyOne loads all datetimes in FiftyOne datasets as naive
`datetime` objects expressed in UTC time.
However, you can configure FiftyOne to express datetimes in a specific timezone
by setting the `timezone` property of your FiftyOne config.
The `timezone` property can be set to any timezone string supported by
`pytz.timezone()`, or `"local"` to use your current local timezone.
For example, you could set the `FIFTYONE_TIMEZONE` environment variable:
```shell
# Local timezone
export FIFTYONE_TIMEZONE=local
# US Eastern timezone
export FIFTYONE_TIMEZONE=US/Eastern
```
Or, you can even dynamically change the timezone while you work in Python:
```python
from datetime import datetime
import fiftyone as fo
sample = fo.Sample(filepath="image.png", created_at=datetime.utcnow())
dataset = fo.Dataset()
dataset.add_sample(sample)
print(sample.created_at)
# 2021-08-24 20:24:09.723021
fo.config.timezone = "local"
dataset.reload()
print(sample.created_at)
# 2021-08-24 16:24:09.723000-04:00
```
#### NOTE
The `timezone` setting does not affect the internal database representation
of datetimes, which are always stored as UTC timestamps.
## Configuring the App
Available in:
Open SourceEnterprise
The [FiftyOne App](app.md#fiftyone-app) can also be configured in various ways.
A new copy of your App config is applied to each [`Session`](../api/fiftyone.core.session.md#fiftyone.core.session.Session) object that is
created when you launch the App. A session’s config can be inspected and
modified via the [`session.config`](../api/fiftyone.core.session.md#fiftyone.core.session.Session.config)
property.
```python
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart")
print(fo.app_config)
session = fo.launch_app(dataset)
print(session.config)
```
#### NOTE
For changes to a live session’s config to take effect in the App, you must
call [`session.refresh()`](../api/fiftyone.core.session.md#fiftyone.core.session.Session.refresh) or
invoke another state-updating action such as `session.view = my_view`.
The FiftyOne App can be configured in the ways described below:
| Config field | Environment variable | Default value | Description |
|-----------------------------|------------------------------------------|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `color_by` | `FIFTYONE_APP_COLOR_BY` | `"field"` | Whether to color labels by their field name (`"field"`), `label` value (`"label"`), or
render each instance ID/trajectory index (`"instance"`). |
| `color_pool` | `FIFTYONE_APP_COLOR_POOL` | See below | A list of browser supported color strings from which the App should draw from when
drawing labels (e.g., object bounding boxes). |
| `colorscale` | `FIFTYONE_APP_COLORSCALE` | `"viridis"` | The colorscale to use when rendering heatmaps in the App. See
[this section](using_datasets.md#heatmaps) for more details. |
| `default_query_performance` | `FIFTYONE_APP_DEFAULT_QUERY_PERFORMANCE` | `True` | Default if a user hasn’t selected a query performance mode in their current session. See
[this section](app.md#app-optimizing-query-performance) for more details. |
| `disable_frame_filtering` | `FIFTYONE_APP_DISABLE_FRAME_FILTERING` | `False` | Whether to disable frame filtering for video datasets in the App’s grid view. See
[this section](app.md#app-optimizing-query-performance) for more details. |
| `enable_query_performance` | `FIFTYONE_APP_ENABLE_QUERY_PERFORMANCE` | `True` | Whether to show the query performance toggle in the UI for users to select. See
[this section](app.md#app-optimizing-query-performance) for more details. |
| `grid_zoom` | `FIFTYONE_APP_GRID_ZOOM` | `5` | The zoom level of the App’s sample grid. Larger values result in larger samples (and thus
fewer samples in the grid). Supported values are `{0, 1, ..., 10}`. |
| `loop_videos` | `FIFTYONE_APP_LOOP_VIDEOS` | `False` | Whether to loop videos by default in the expanded sample view. |
| `max_query_time` | `FIFTYONE_APP_MAX_QUERY_TIME` | `60` | Maximum query time in seconds for potentially slow sidebar and grid requests. Only applies
when [Query Performance](app.md#app-optimizing-query-performance) is enabled. |
| `media_fallback` | `FIFTYONE_APP_MEDIA_FALLBACK` | `False` | Whether to fall back to the default media field (`"filepath"`) when the configured media
field’s value for a sample is not defined. |
| `multicolor_keypoints` | `FIFTYONE_APP_MULTICOLOR_KEYPOINTS` | `False` | Whether to independently color keypoint points by their index |
| `notebook_height` | `FIFTYONE_APP_NOTEBOOK_HEIGHT` | `800` | The height of App instances displayed in notebook cells. |
| `proxy_url` | `FIFTYONE_APP_PROXY_URL` | `None` | A URL string to override the default server URL. Useful for configuring the session
through a reverse proxy in notebook environments. |
| `show_confidence` | `FIFTYONE_APP_SHOW_CONFIDENCE` | `True` | Deprecated; has no effect. Label attribute visibility is controlled per attribute in the
App’s sidebar. |
| `show_index` | `FIFTYONE_APP_SHOW_INDEX` | `True` | Deprecated; has no effect. Label attribute visibility is controlled per attribute in the
App’s sidebar. |
| `show_label` | `FIFTYONE_APP_SHOW_LABEL` | `True` | Deprecated; has no effect. Label attribute visibility is controlled per attribute in the
App’s sidebar. |
| `show_skeletons` | `FIFTYONE_APP_SHOW_SKELETONS` | `True` | Whether to show keypoint skeletons, if available. |
| `show_tooltip` | `FIFTYONE_APP_SHOW_TOOLTIP` | `True` | Whether to show the tooltip when hovering over labels in the App’s expanded sample view. |
| `theme` | `FIFTYONE_APP_THEME` | `"browser"` | The default theme to use in the App. Supported values are `{"browser", "dark", "light"}`.
If `"browser"`, your current theme will be persisted in your browser’s storage. |
| `use_frame_number` | `FIFTYONE_APP_USE_FRAME_NUMBER` | `False` | Whether to use the frame number instead of a timestamp in the expanded sample view. Only
applicable to video samples. |
| `plugins` | N/A | `{}` | A dict of plugin configurations. See [this section](#configuring-plugins) for
details. |
## Viewing your App config
You can print your App config at any time via the Python library and the CLI:
Python
CLI
```python
import fiftyone as fo
# Print your current App config
print(fo.app_config)
# Print a specific App config field
print(fo.app_config.show_skeletons)
```
```text
{
"color_by": "field",
"color_pool": [
"#ee0000",
"#ee6600",
"#993300",
"#996633",
"#999900",
"#009900",
"#003300",
"#009999",
"#000099",
"#0066ff",
"#6600ff",
"#cc33cc",
"#777799"
],
"colorscale": "viridis",
"frame_stream_size": 1000,
"grid_zoom": 5,
"loop_videos": false,
"media_fallback": false,
"default_query_performance": true,
"disable_frame_filtering": false,
"enable_query_performance": true,
"multicolor_keypoints": false,
"notebook_height": 800,
"proxy_url": None,
"show_confidence": true,
"show_index": true,
"show_label": true,
"show_skeletons": true,
"show_tooltip": true,
"sidebar_mode": "fast",
"theme": "browser",
"use_frame_number": false,
"plugins": {},
}
True
```
```shell
# Print your current App config
fiftyone app config
# Print a specific App config field
fiftyone app config show_skeletons
```
```text
{
"color_by": "field",
"color_pool": [
"#ee0000",
"#ee6600",
"#993300",
"#996633",
"#999900",
"#009900",
"#003300",
"#009999",
"#000099",
"#0066ff",
"#6600ff",
"#cc33cc",
"#777799"
],
"colorscale": "viridis",
"frame_stream_size": 1000,
"grid_zoom": 5,
"default_query_performance": true,
"disable_frame_filtering": false,
"enable_query_performance": true,
"loop_videos": false,
"media_fallback": false,
"multicolor_keypoints": false,
"notebook_height": 800,
"proxy_url": None,
"show_confidence": true,
"show_index": true,
"show_label": true,
"show_skeletons": true,
"show_tooltip": true,
"sidebar_mode": "fast",
"theme": "browser",
"use_frame_number": false,
"plugins": {},
}
True
```
#### NOTE
If you have customized your App config via any of the methods described
below, printing your config is a convenient way to ensure that the changes
you made have taken effect as you expected.
## Modifying your App config
You can modify your App config in a variety of ways. The following sections
describe these options in detail.
#### NOTE
Did you know? You can also configure the behavior of the App on a
per-dataset basis by customizing your
[dataset’s App config](using_datasets.md#dataset-app-config).
### Order of precedence
The following order of precedence is used to assign values to your App config
settings at runtime:
1. Config settings of a
[`Session`](../api/fiftyone.core.session.md#fiftyone.core.session.Session) instance in question
2. App config settings applied at runtime by directly editing
`fiftyone.app_config`
3. `FIFTYONE_APP_XXX` environment variables
4. Settings in your JSON App config (`~/.fiftyone/app_config.json`)
5. The default App config values
### Launching the App with a custom config
You can launch the FiftyOne App with a customized App config on a one-off basis
via the following pattern:
```python
import fiftyone as fo
import fiftyone.zoo as foz
dataset = foz.load_zoo_dataset("quickstart")
# Create a custom App config
app_config = fo.app_config.copy()
app_config.show_skeletons = False
app_config.loop_videos = True
session = fo.launch_app(dataset, config=app_config)
```
You can also configure a live [`Session`](../api/fiftyone.core.session.md#fiftyone.core.session.Session) by editing its
[`session.config`](../api/fiftyone.core.session.md#fiftyone.core.session.Session.config) property and
calling [`session.refresh()`](../api/fiftyone.core.session.md#fiftyone.core.session.Session.refresh) to
apply the changes:
```python
# Customize the config of a live session
session.config.show_skeletons = True
session.config.loop_videos = False
session.refresh() # must refresh after edits
```
### Editing your JSON App config
You can permanently customize your App config by creating a
`~/.fiftyone/app_config.json` file on your machine. The JSON file may contain
any desired subset of config fields that you wish to customize.
For example, a valid App config JSON file is:
```json
{
"show_skeletons": false,
"loop_videos": true
}
```
When `fiftyone` is imported, any options from your JSON App config are applied,
as per the order of precedence described above.
#### NOTE
You can customize the location from which your JSON App config is read by
setting the `FIFTYONE_APP_CONFIG_PATH` environment variable.
### Setting App environment variables
App config settings may be customized on a per-session basis by setting the
`FIFTYONE_APP_XXX` environment variable(s) for the desired App config settings.
When `fiftyone` is imported, all App config environment variables are applied,
as per the order of precedence described above.
For example, you can customize your App config in a Terminal session by
issuing the following commands prior to launching your Python interpreter:
```shell
export FIFTYONE_APP_SHOW_CONFIDENCE=false
export FIFTYONE_APP_SHOW_LABEL=false
```
### Modifying your App config in code
You can dynamically modify your App config at runtime by editing the
`fiftyone.app_config` object.
Any changes to your App config applied via this manner will immediately
take effect for all subsequent calls to `fiftyone.app_config` during your
current session.
```python
import fiftyone as fo
fo.app_config.show_skeletons = False
fo.app_config.loop_videos = True
```
## Configuring plugins
You can store system-wide plugin configurations under the `plugins` key of your
App config.
Builtin plugins that you can configure include:
- The builtin [Map panel](app.md#app-map-panel)
- The builtin [3D visualizer](app.md#app-3d-visualizer-config)
- Any [custom plugins](../plugins/overview.md#fiftyone-plugins) that you’ve registered
For example, you may add the following to your JSON App config
(`~/.fiftyone/app_config.json`) to register a Mapbox token globally on your
system:
```text
{
"plugins": {
"map": {
"mapboxAccessToken": "XXXXXXXX"
}
}
}
```
#### NOTE
You can also store dataset-specific plugin settings by storing any subset
of the above values on a [dataset’s App config](using_datasets.md#dataset-app-config).
## Configuring a proxy URL
When running FiftyOne in a cloud machine, such as a
[SageMaker Notebook](https://aws.amazon.com/sagemaker/notebooks/), a
`proxy_url` should be set in your
[FiftyOne App config](#configuring-fiftyone-app) before launching the App
in order for browser windows or notebook cells to point to a correct App URL.
For [SageMaker Notebooks](https://aws.amazon.com/sagemaker/notebooks/), the
below code snippet shows how to configure the proxy based on your instance.
```python
import fiftyone as fo
# before launching the App, configure a proxy_url
fo.app_config.proxy_url = "https://.notebook..sagemaker.aws/proxy//"
session = fo.launch_app(port=)
```