<!-- # hard line break macro for HTML -->

# fiftyone.core.service

FiftyOne Services.

Copyright 2017-2026, Voxel51, Inc.
<br/>
[voxel51.com](https://voxel51.com/)
<br/>
<br/>

**Exceptions:**

| [`ServiceException`](#fiftyone.core.service.ServiceException)                       | Base class for service-related exceptions.                             |
|-------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| [`ServiceListenTimeout`](#fiftyone.core.service.ServiceListenTimeout)(name[, port]) | Exception raised when a network-bound service fails to bind to a port. |
| [`ServiceExecutableNotFound`](#fiftyone.core.service.ServiceExecutableNotFound)     | Exception raised when the service executable is not found on disk.     |

**Classes:**

| [`Service`](#fiftyone.core.service.Service)()                                          | Interface for FiftyOne services.                       |
|----------------------------------------------------------------------------------------|--------------------------------------------------------|
| [`MultiClientService`](#fiftyone.core.service.MultiClientService)()                    | Base class for services that support multiple clients. |
| [`DatabaseService`](#fiftyone.core.service.DatabaseService)()                          | Service that controls the underlying MongoDB database. |
| [`ServerService`](#fiftyone.core.service.ServerService)(port[, address, do_not_track]) | Service that controls the FiftyOne web server.         |

### *exception* fiftyone.core.service.ServiceException

Bases: `Exception`

Base class for service-related exceptions.

**Methods:**

| [`add_note`](#fiftyone.core.service.ServiceException.add_note)(object, /)             | Exception.add_note(note) -- add a note to the exception                         |
|---------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| [`with_traceback`](#fiftyone.core.service.ServiceException.with_traceback)(object, /) | Exception.with_traceback(tb) -- set self._\_traceback_\_ to tb and return self. |

**Attributes:**

| [`args`](#fiftyone.core.service.ServiceException.args)   |    |
|----------------------------------------------------------|----|

#### add_note(object,)

Exception.add_note(note) –
add a note to the exception

#### args

#### with_traceback(object,)

Exception.with_traceback(tb) –
set self._\_traceback_\_ to tb and return self.

### *exception* fiftyone.core.service.ServiceListenTimeout(name, port=None)

Bases: [`ServiceException`](#fiftyone.core.service.ServiceException)

Exception raised when a network-bound service fails to bind to a port.

**Methods:**

| [`add_note`](#fiftyone.core.service.ServiceListenTimeout.add_note)(object, /)             | Exception.add_note(note) -- add a note to the exception                         |
|-------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| [`with_traceback`](#fiftyone.core.service.ServiceListenTimeout.with_traceback)(object, /) | Exception.with_traceback(tb) -- set self._\_traceback_\_ to tb and return self. |

**Attributes:**

| [`args`](#fiftyone.core.service.ServiceListenTimeout.args)   |    |
|--------------------------------------------------------------|----|

#### add_note(object,)

Exception.add_note(note) –
add a note to the exception

#### args

#### with_traceback(object,)

Exception.with_traceback(tb) –
set self._\_traceback_\_ to tb and return self.

### *exception* fiftyone.core.service.ServiceExecutableNotFound

Bases: [`ServiceException`](#fiftyone.core.service.ServiceException)

Exception raised when the service executable is not found on disk.

**Methods:**

| [`add_note`](#fiftyone.core.service.ServiceExecutableNotFound.add_note)(object, /)             | Exception.add_note(note) -- add a note to the exception                         |
|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| [`with_traceback`](#fiftyone.core.service.ServiceExecutableNotFound.with_traceback)(object, /) | Exception.with_traceback(tb) -- set self._\_traceback_\_ to tb and return self. |

**Attributes:**

| [`args`](#fiftyone.core.service.ServiceExecutableNotFound.args)   |    |
|-------------------------------------------------------------------|----|

#### add_note(object,)

Exception.add_note(note) –
add a note to the exception

#### args

#### with_traceback(object,)

Exception.with_traceback(tb) –
set self._\_traceback_\_ to tb and return self.

### *class* fiftyone.core.service.Service

Bases: `object`

Interface for FiftyOne services.

All services must define a `command` property.

Services are run in an isolated Python subprocess (see `service/main.py`)
to ensure that they are shut down when the main Python process exits. The
`command` and `working_dir` properties control the execution of the
service in the subprocess.

**Attributes:**

| [`service_name`](#fiftyone.core.service.Service.service_name)     |    |
|-------------------------------------------------------------------|----|
| [`working_dir`](#fiftyone.core.service.Service.working_dir)       |    |
| [`allow_headless`](#fiftyone.core.service.Service.allow_headless) |    |
| [`command`](#fiftyone.core.service.Service.command)               |    |
| [`env`](#fiftyone.core.service.Service.env)                       |    |

**Methods:**

| [`start`](#fiftyone.core.service.Service.start)()   | Starts the service.                                      |
|-----------------------------------------------------|----------------------------------------------------------|
| [`stop`](#fiftyone.core.service.Service.stop)()     | Stops the service.                                       |
| [`wait`](#fiftyone.core.service.Service.wait)()     | Waits for the service to exit and returns its exit code. |

#### service_name *= None*

#### working_dir *= '.'*

#### allow_headless *= False*

#### *property* command

#### *property* env

#### start()

Starts the service.

#### stop()

Stops the service.

#### wait()

Waits for the service to exit and returns its exit code.

### *class* fiftyone.core.service.MultiClientService

Bases: [`Service`](#fiftyone.core.service.Service)

Base class for services that support multiple clients.

**Attributes:**

| [`attached`](#fiftyone.core.service.MultiClientService.attached)             |    |
|------------------------------------------------------------------------------|----|
| [`allow_headless`](#fiftyone.core.service.MultiClientService.allow_headless) |    |
| [`command`](#fiftyone.core.service.MultiClientService.command)               |    |
| [`env`](#fiftyone.core.service.MultiClientService.env)                       |    |
| [`service_name`](#fiftyone.core.service.MultiClientService.service_name)     |    |
| [`working_dir`](#fiftyone.core.service.MultiClientService.working_dir)       |    |

**Methods:**

| [`start`](#fiftyone.core.service.MultiClientService.start)()   | Searches for a running instance of this service, or starts one if no instance is found.   |
|----------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| [`stop`](#fiftyone.core.service.MultiClientService.stop)()     | Disconnects from the service without actually stopping it.                                |
| [`wait`](#fiftyone.core.service.MultiClientService.wait)()     | Waits for the service to exit and returns its exit code.                                  |

#### attached *= False*

#### start()

Searches for a running instance of this service, or starts one
if no instance is found.

#### stop()

Disconnects from the service without actually stopping it.

#### allow_headless *= False*

#### *property* command

#### *property* env

#### service_name *= None*

#### wait()

Waits for the service to exit and returns its exit code.

#### working_dir *= '.'*

### *class* fiftyone.core.service.DatabaseService

Bases: [`MultiClientService`](#fiftyone.core.service.MultiClientService)

Service that controls the underlying MongoDB database.

**Attributes:**

| [`service_name`](#fiftyone.core.service.DatabaseService.service_name)       |    |
|-----------------------------------------------------------------------------|----|
| [`allow_headless`](#fiftyone.core.service.DatabaseService.allow_headless)   |    |
| [`MONGOD_EXE_NAME`](#fiftyone.core.service.DatabaseService.MONGOD_EXE_NAME) |    |
| [`command`](#fiftyone.core.service.DatabaseService.command)                 |    |
| [`port`](#fiftyone.core.service.DatabaseService.port)                       |    |
| [`attached`](#fiftyone.core.service.DatabaseService.attached)               |    |
| [`env`](#fiftyone.core.service.DatabaseService.env)                         |    |
| [`working_dir`](#fiftyone.core.service.DatabaseService.working_dir)         |    |

**Methods:**

| [`find_mongod`](#fiftyone.core.service.DatabaseService.find_mongod)()   | Returns the path to the `mongod` executable.                                            |
|-------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| [`start`](#fiftyone.core.service.DatabaseService.start)()               | Searches for a running instance of this service, or starts one if no instance is found. |
| [`stop`](#fiftyone.core.service.DatabaseService.stop)()                 | Disconnects from the service without actually stopping it.                              |
| [`wait`](#fiftyone.core.service.DatabaseService.wait)()                 | Waits for the service to exit and returns its exit code.                                |

#### service_name *= 'db'*

#### allow_headless *= True*

#### MONGOD_EXE_NAME *= 'mongod'*

#### *property* command

#### *property* port

#### *static* find_mongod()

Returns the path to the `mongod` executable.

#### attached *= False*

#### *property* env

#### start()

Searches for a running instance of this service, or starts one
if no instance is found.

#### stop()

Disconnects from the service without actually stopping it.

#### wait()

Waits for the service to exit and returns its exit code.

#### working_dir *= '.'*

### *class* fiftyone.core.service.ServerService(port, address=None, do_not_track=False)

Bases: [`Service`](#fiftyone.core.service.Service)

Service that controls the FiftyOne web server.

**Attributes:**

| [`service_name`](#fiftyone.core.service.ServerService.service_name)     |    |
|-------------------------------------------------------------------------|----|
| [`working_dir`](#fiftyone.core.service.ServerService.working_dir)       |    |
| [`allow_headless`](#fiftyone.core.service.ServerService.allow_headless) |    |
| [`command`](#fiftyone.core.service.ServerService.command)               |    |
| [`port`](#fiftyone.core.service.ServerService.port)                     |    |
| [`address`](#fiftyone.core.service.ServerService.address)               |    |
| [`env`](#fiftyone.core.service.ServerService.env)                       |    |

**Methods:**

| [`start`](#fiftyone.core.service.ServerService.start)()   | Starts the service.                                      |
|-----------------------------------------------------------|----------------------------------------------------------|
| [`stop`](#fiftyone.core.service.ServerService.stop)()     | Stops the service.                                       |
| [`wait`](#fiftyone.core.service.ServerService.wait)()     | Waits for the service to exit and returns its exit code. |

#### service_name *= 'server'*

#### working_dir *= '/opt/hostedtoolcache/Python/3.13.15/x64/lib/python3.13/site-packages/fiftyone/server'*

#### allow_headless *= True*

#### start()

Starts the service.

#### *property* command

#### *property* port

#### *property* address

#### *property* env

#### stop()

Stops the service.

#### wait()

Waits for the service to exit and returns its exit code.