TheFirebase Local Emulator Suiteemulates products for a single Firebase project.
To select the project to use, before you start the emulators, in the CLI runfirebase usein your working directory. Or, you can pass
the --project flag to each emulator
command.
Local Emulator Suitesupports emulation ofrealFirebase projects anddemoprojects.
Project type
Features
Use with emulators
Real
A real Firebase project is one you created and configured (most likely
via theFirebaseconsole).
Real projects have live resources, like database instances, storage
buckets, functions, or any other resource you set up for that Firebase
project.
When working with real Firebase projects, you can run emulators for any
or all of the supported products.
For any products you are not emulating, your apps and code will
interact with theliveresource (database instance, storage
bucket, function, etc.).
Demo
A demo Firebase project has norealFirebase configuration and
no live resources. These projects are usually accessed via codelabs or
other tutorials.
Project IDs for demo projects have thedemo-prefix.
When working with demo Firebase projects, your apps and code interact with
emulatorsonly. If your app attempts to interact with a resource
for which an emulator isn't running, that code will fail.
We recommend you use demo projects wherever possible. Benefits include:
Easier setup, since you can run the emulators without ever creating a
Firebase project
Stronger safety, since if your code accidentally invokes non-emulated
(production) resources, there is no chance of data change, usage and billing
Better offline support, since there is no need to access the internet to
download your SDK configuration.
Instrument your app to talk to the emulators
On startup, theCloud Firestoreemulator creates a default database and a named
database for eachfirestoreconfiguration in yourfirebase.jsonfile.
Named databases are also created implicitly in response to any SDK or
REST API calls to the emulator that reference a specific database. Such
implicitly-created databases operate withopen rules.
To work with your default and named databases interactively in theEmulator Suite UI, in your browser's address bar, update the URL to select
either the default or a named database.
For example, to browse the data in your default instance, update the URL tolocalhost:4000/firestore/default/data
To browse in an instance namedecommerce, update tolocalhost:4000/firestore/ecommerce/data.
Android, Apple platforms, and Web SDKs
Set up your in-app configuration or test classes to interact withCloud Firestoreas follows. Note that in the following samples, app code
is connecting to the default project database. For examples involving additionalCloud Firestoredatabases beyond the default database, refer to theguide for multiple databases.
Kotlin
// 10.0.2.2 is the special IP address to connect to the 'localhost' of// the host computer from an Android emulator.valfirestore=Firebase.firestorefirestore.useEmulator("10.0.2.2",8080)firestore.firestoreSettings=firestoreSettings{isPersistenceEnabled=false}
// 10.0.2.2 is the special IP address to connect to the 'localhost' of// the host computer from an Android emulator.FirebaseFirestorefirestore=FirebaseFirestore.getInstance();firestore.useEmulator("10.0.2.2",8080);FirebaseFirestoreSettingssettings=newFirebaseFirestoreSettings.Builder().setPersistenceEnabled(false).build();firestore.setFirestoreSettings(settings);
No additional setup is needed to test Cloud Functionstriggered by Firestore eventsusing the emulator. When the Firestore and Cloud Functions emulators are both
running, they automatically work together.
Admin SDKs
TheFirebaseAdmin SDKs automatically connect to theCloud Firestoreemulator when theFIRESTORE_EMULATOR_HOSTenvironment variable is set:
exportFIRESTORE_EMULATOR_HOST="127.0.0.1:8080"
If your code is running inside theCloud Functionsemulator your project ID
and other configuration are automatically set when callinginitializeApp.
If you want yourAdmin SDKcode to connect to a shared emulator running in
another environment, you need to specify thethe same project ID you set using the Firebase CLI.
You can pass a project ID toinitializeAppdirectly or set theGCLOUD_PROJECTenvironment variable.
Production Firestore provides no platform SDK method for flushing the database, but the Firestore emulator gives you a REST endpoint specifically for this purpose, which can be called from a test framework setup/tearDown step, from a test class, or from the shell (e.g., withcurl) before a test is kicked off. You can use this approach as an alternative to simply shutting down the emulator process.
In an appropriate method, perform an HTTP DELETE operation, supplying your
Firebase projectID, for examplefirestore-emulator-example, to the following
endpoint:
Having implemented a step like this, you can sequence your tests and trigger
your functions with confidence that old data will be purged between runs and
you're using a fresh baseline test configuration.
Import and export data
The database andCloud Storage for Firebaseemulators allow you to export data
from a running emulator instance. Define a baseline set of data to use in your
unit tests or continuous integration workflows, then export it to be shared
among the team.
firebaseemulators:export./dir
In tests, on emulator startup, import the baseline data.
firebaseemulators:start--import=./dir
You can instruct the emulator to export data on shutdown, either specifying an
export path or simply using the path passed to the--importflag.
This breaks your rules into expressions and subexpressions that you can
mouseover for more information, including number of evaluations and values
returned. For the raw JSON version of this data, include the following URL
in your query:
Here, the HTML version of the report highlights evaluations that throw undefined and null-value errors:
How theCloud Firestoreemulator differs from production
TheCloud FirestoreEmulator attempts to faithfully replicate the behavior
of the production service with some notable limitations.
Multiple database support forCloud Firestore
Currently, theEmulator Suite UIsupports interactive creation, editing,
deletion, request monitoring, and security visualization for a default database,
but not additional named databases.
However, the emulator itself does create a named database based on the
configuration in yourfirebase.jsonfile and implicitly in response to SDK or
REST API calls.
Transactions
The emulator does not currently implement all transaction behavior
seen in production. When you're testing features that involve multiple
concurrent writes to one document, the emulator may be slow to complete write
requests. In some cases, locks may take up to 30 seconds to be released.
Consider adjusting test timeouts accordingly, if needed.
Indexes
The emulator does not track compound indexes and instead will execute any
valid query. Make sure to test your app against a realCloud Firestoreinstance to determine which indexes you will need.
Limits
The emulator does not enforce all limits enforced in production. For example,
the emulator may allow transactions that would be rejected as too large by the
production service. Make sure you are familiar with thedocumented limitsand that you design your app to
proactively avoid them.
Since triggered functions are a typical integration withCloud Firestore,
learn more about theCloud Functions for Firebaseemulator atRun functions locally.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,[]]
