Install and run

Prerequisites

Before you start

• Node.js 20 or newer (the package’s engines field is >=20). It runs the fireemu launcher and the Functions runner.
• A supported platform. The package installs a prebuilt binary for your platform; no Java or other runtime is needed.

OS	Architecture
macOS 13 or newer	Apple silicon, Intel
Linux (any glibc or musl distribution, including Alpine and distroless)	x86-64, arm64
Windows 10 or newer	x86-64
:::

To run Cloud Functions you also need firebase-functions v6 or v7 in the codebase. A Python codebase needs Python 3.10 to 3.14 and its own venv with firebase-functions instead (macOS and Linux; see Cloud Functions).

Install

Add Fireemu as a development dependency of your project. The package installs a prebuilt binary for your platform.

npm install --save-dev fireemu

Create fireemu.toml

npx fireemu init

init creates fireemu.toml in the current directory. Interactively, it asks which compatibility profile to use (strict, the default, is recommended) and whether to reuse an existing firebase.json. When you reuse it, Fireemu references the file instead of copying it: Security Rules, indexes, Functions codebases and ports are read from it every time Fireemu starts.

For CI or a script, use the non-interactive form. An existing fireemu.toml is not overwritten unless you pass --force. An existing fireemu.json is preserved; remove it before creating fireemu.toml.

npx fireemu init --yes

npx fireemu init --yes writes exactly this file (the comments are added here to explain each line):

TOML

# Editor hint: points TOML-aware editors at the JSON Schema for completion and validation.
#:schema https://raw.githubusercontent.com/fireemu/fireemu/main/spec/config/fireemu.schema.json
# The configuration format version. The only value is 1.
schemaVersion = 1
# "strict" follows production (the default and recommended); "emulator" follows the pinned official emulator.
profile = "strict"
# The same schema URL as a data key, so JSON-oriented tools find it.
"$schema" = "https://raw.githubusercontent.com/fireemu/fireemu/main/spec/config/fireemu.schema.json"
# "native" (Firestore Native mode API) or "mongodb-compatible".
firestore.apiMode = "native"
# "standard" or "enterprise".
firestore.edition = "standard"

JSON

{
  "schemaVersion": 1,
  "profile": "strict",
  "$schema": "https://raw.githubusercontent.com/fireemu/fireemu/main/spec/config/fireemu.schema.json",
  "firestore": {
    "edition": "standard",
    "apiMode": "native"
  }
}

The JSON tab is the equivalent fireemu.json, which init does not write. When ./firebase.json exists (or you pass --firebase-json <file>), init references it and adds one more line, firebaseJson = "firebase.json", so ports, Security Rules, indexes and Functions codebases are read from that file. Every key is listed in the configuration schema; npx fireemu init --reference also writes fireemu.reference.toml, which describes every key and is not loaded.

Start the emulators

npx fireemu up

up keeps the emulators running until you press Ctrl+C. Open the Emulator UI at http://127.0.0.1:4000/ui/ to inspect and manage data.

The first lines of the startup output name the configuration files that were loaded and say, for Firestore and Storage, whether Security Rules are loaded.

Run a command against the emulators

To run the emulators only for the duration of a command, such as your test suite, use exec:

npx fireemu exec -- npm test

exec starts the emulators, runs the command once every listener is ready, with the Firebase SDK emulator environment variables set (see Connect your app), stops everything when the command exits, and exits with the command’s status. On Unix, SIGINT and SIGTERM are forwarded to the command. exec does not start the UI unless you add --ui.

The official command names are available as aliases:

npx fireemu emulators:start
npx fireemu emulators:exec -- npm test

Choose services

By default Fireemu starts Firestore, Authentication, Storage and App Check. These start only when configured:

• Functions, and with it Eventarc and Cloud Tasks, when a codebase is configured.
• Pub/Sub, when emulators.pubsub, daemon.pubsubPort or --pubsub-port is set.
• Realtime Database, when emulators.database, daemon.databasePort or --database-port is set.
• Hosting, when firebase.json has a hosting.public directory.

Use --only to choose exactly which services start:

npx fireemu up --only auth,firestore,storage
npx fireemu exec --only firestore -- npm test

# One Functions codebase
npx fireemu up --only functions:<codebase>

Default ports

Fireemu uses the same default ports as the Local Emulator Suite. A port set in firebase.json or on the command line takes precedence.

Service	Port	Option
Emulator UI	4000	--ui-port
Emulator Hub	4400	--hub-port
Logging	4500	--logging-port
Firebase Hosting	5000	--hosting-port
Cloud Functions	5001	--functions-port
Cloud Firestore	8080	--firestore-port
Cloud Pub/Sub	8085	--pubsub-port
Realtime Database	9000	--database-port
Authentication	9099	--http-port
Cloud Storage	9199	--storage-port
Eventarc	9299	--eventarc-port
Cloud Tasks	9499	--tasks-port

Next steps

Connect your app to the emulators, or see Migrate from the Local Emulator Suite if you already use firebase emulators:exec.

Get help

Every command documents its options:

npx fireemu --help
npx fireemu exec --help

If the emulators do not start, run npx fireemu doctor. See Troubleshooting.