Use Firestore emulator locally

The Google Cloud CLI provides a local, in-memory emulator for Firestore that you can use to test your application. You can use the emulator with all Firestore client libraries. You should use the emulator only for local testing.

Do not use the emulator for production deployments. Because the emulator stores data only in memory, it will not persist data across runs.

Install the emulator

To install the Firestore emulator, install and update the gcloud CLI:

Install the gcloud CLI.
Update your gcloud CLI installation to get the latest features:
```
gcloud components update
```

Run the emulator

Run the following command to start the emulator:
```
gcloud emulators firestore start
```
The emulator prints the host and port number where it is running.

By default, the emulator attempts to use 127.0.0.1:8080. To bind the emulator to a specific host and port, use the optional --host-port flag, replacing HOST and PORT:
```
gcloud emulators firestore start --host-port=HOST:PORT
```
Type Control + C to stop the emulator. The emulator may also be stopped with a POST to /shutdown. For example:
```
curl -d '' HOST:PORT/shutdown
```

Connect to the emulator

How you connect to the emulator depends on the type of client library, server client library, or mobile/web SDK.

Server client libraries

To connect a Firestore server client library (C#, Go, Java, Node.js, PHP, Python, and Ruby), set the FIRESTORE_EMULATOR_HOST environment variable. When this environment variable is set, the server client libraries automatically connect to the emulator.

export FIRESTORE_EMULATOR_HOST="HOST:PORT"

Android, Apple platforms, and Web SDKs

The following examples demonstrate how to connect the Android, Apple platforms, and Web SDKs to the Firestore emulator:

Android

// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFirestore firestore = FirebaseFirestore.getInstance();
firestore.useEmulator("10.0.2.2", 8080);

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(false)
        .build();
firestore.setFirestoreSettings(settings);EmulatorSuite.java

Swift

let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settingsViewController.swift

Web version 9

import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, '127.0.0.1', 8080);fs_emulator_connect.js

Web version 8

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("127.0.0.1", 8080);
}emulator-suite.js

The Firestore emulator clears database contents when shut down. Since the offline cache of the Firestore SDK is not automatically cleared, you may want to disable local persistence in your emulator configuration to avoid discrepancies between the emulated database and local caches; in the Web SDK, persistence is disabled by default.

Clear emulator data

The Firestore emulator includes a REST endpoint for deleting all the data currently in the emulator. You can use this endpoint to clear data between tests without shutting down the emulator.

To delete all data in the emulator, perform an HTTP DELETE operation against the following endpoint, replacing HOST and PORT with the host and port you selected and replacing PROJECT_ID with your own project ID:

http://HOST:PORT/emulator/v1/projects/PROJECT_ID/databases/(default)/documents

Adjust the host and port if the emulator does not use 127.0.0.1:8080. Your code should await REST confirmation that the deletion finished or failed.

You can perform this operation from the shell using curl:

$ curl -v -X DELETE "http://HOST:PORT/emulator/v1/projects/PROJECT_ID/databases/(default)/documents"

How the Firestore emulator differs from production

The Firestore emulator attempts to faithfully replicate the behavior of the production service with some notable limitations.

Transactions

The emulator does not 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 composite indexes and will instead execute any valid query. Make sure to test your app against a real Firestore instance to determine which indexes you require.

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 the documented limits and that you design your app to proactively avoid them.