Stay organized with collectionsSave and categorize content based on your preferences.
Use Firestore emulator locally
TheGoogle Cloud CLIprovides 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:
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 use127.0.0.1:8080. To bind the
emulator to a specific host and port, use the optional--host-portflag,
replacingHOSTandPORT:
TypeControl + Cto 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 theFIRESTORE_EMULATOR_HOSTenvironment variable. When this environment
variable is set, the server client libraries automatically connect to the emulator.
exportFIRESTORE_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.FirebaseFirestorefirestore=FirebaseFirestore.getInstance();firestore.useEmulator("10.0.2.2",8080);FirebaseFirestoreSettingssettings=newFirebaseFirestoreSettings.Builder().setPersistenceEnabled(false).build();firestore.setFirestoreSettings(settings);
The Firestore in Native Mode 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 HTTPDELETEoperation against
the following endpoint, replacingHOSTandPORTwith the
host and port you selected and replacingPROJECT_IDwith your
own project ID:
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 doesn't attempt to mimic the transaction behavior that's seen in
production. It uses a simple locking approach and doesn't attempt to mirror
the various concurrency modes offered in the production environment.
When you're testing features that involve multiple concurrent writes to one
document, the emulator might be slow to complete write requests. It might take
up to 30 seconds for the emulator to release the locks. If you need to adjust
the test timeout intervals, then do so.
The emulator doesn't also attempt to mimic all of theproduction limits, such as
timeouts & size limits, which involve transactions. If you test features that
depend on these production limits, then we recommend that you use a production
environment instead of an emulator.
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 thedocumented limitsand that you design your app to
proactively avoid them.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["# Use Firestore emulator locally\n==============================\n\nThe [Google Cloud CLI](/sdk) provides a local, in-memory emulator for\nFirestore that you can use to test your application. You can use the\nemulator with all Firestore client libraries. You should use\nthe emulator only for local testing.\n\nDo not use the emulator for production deployments. Because the emulator stores\ndata only in memory, it will not persist data across runs.\n| **Tip:** The instructions on this page show you how to run the Firestore emulator using the gcloud CLI. The same Firestore emulator is also available through the [Firebase Local Emulator Suite](https://firebase.google.com/docs/emulator-suite#what-is-emulator-suite). The emulator suite bundles several emulators and helps you test these services together. To access the Firestore emulator through the emulator suite, see [Introduction to Firebase Local Emulator Suite](https://firebase.google.com/docs/emulator-suite).\n\nInstall the emulator\n--------------------\n\n| **Note:** The Firestore emulator will be updated to require Java 21 in the upcoming Google Cloud CLI release 528.0.0. Upgrade to Java 21 or later to continue using the latest version of the emulator.\n\nTo install the Firestore emulator, install and update the\ngcloud CLI:\n\n1. [Install the gcloud CLI](/sdk/docs/install).\n\n2. Update your gcloud CLI installation to get the latest\n features:\n\n gcloud components update\n\nRun the emulator\n----------------\n\n1. Run the following command to start the emulator:\n\n gcloud emulators firestore start\n\n The emulator prints the host and port number where it is running.\n\n By default, the emulator attempts to use `127.0.0.1:8080`. To bind the\n emulator to a specific host and port, use the optional `--host-port` flag,\n replacing \u003cvar translate=\"no\"\u003eHOST\u003c/var\u003e and \u003cvar translate=\"no\"\u003ePORT\u003c/var\u003e: \n\n gcloud emulators firestore start --host-port=\u003cvar translate=\"no\"\u003eHOST\u003c/var\u003e:\u003cvar translate=\"no\"\u003ePORT\u003c/var\u003e\n\n2. Type `Control + C` to stop the emulator. The emulator may also be stopped\n with a POST to `/shutdown`. For example:\n\n curl -d '' \u003cvar translate=\"no\"\u003eHOST\u003c/var\u003e:\u003cvar translate=\"no\"\u003ePORT\u003c/var\u003e/shutdown\n\nConnect to the emulator\n-----------------------\n\nHow you connect to the emulator depends on the type of client library, server\nclient library, or mobile/web SDK.\n\n### Server client libraries\n\nTo connect a Firestore server client\nlibrary (C#, Go, Java, Node.js, PHP, Python, and Ruby),\nset the `FIRESTORE_EMULATOR_HOST` environment variable. When this environment\nvariable is set, the server client libraries automatically connect to the emulator. \n\n export FIRESTORE_EMULATOR_HOST=\"\u003cvar translate=\"no\"\u003eHOST\u003c/var\u003e:\u003cvar translate=\"no\"\u003ePORT\u003c/var\u003e\"\n\n### Android, Apple platforms, and Web SDKs\n\nThe following examples demonstrate how to connect the\nAndroid, Apple platforms, and Web SDKs to the Firestore\nemulator: \n\n##### Android\n\n```carbon\n// 10.0.2.2 is the special IP address to connect to the 'localhost' of\n// the host computer from an Android emulator.\nFirebaseFirestore firestore = FirebaseFirestore.getInstance();\nfirestore.useEmulator(\"10.0.2.2\", 8080);\n\nFirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()\n .setPersistenceEnabled(false)\n .build();\nfirestore.setFirestoreSettings(settings);https://github.com/firebase/snippets-android/blob/391c1646eacf44d2aab3f76bcfa60dfc6c14acf1/firestore/app/src/main/java/com/google/example/firestore/EmulatorSuite.java#L10-L18\n```\n\n##### Swift\n\n```swift\nlet settings = Firestore.firestore().settings\nsettings.host = \"127.0.0.1:8080\"\nsettings.cacheSettings = MemoryCacheSettings()\nsettings.isSSLEnabled = false\nFirestore.firestore().settings = settings \nhttps://github.com/firebase/snippets-ios/blob/cdce007fedb3bb90dd3a70ce03066178236e1deb/firestore/swift/firestore-smoketest/ViewController.swift#L1251-L1255\n```\n\n### Web version 9\n\n```javascript\nimport { getFirestore, connectFirestoreEmulator } from \"firebase/firestore\";\n\n// firebaseApps previously initialized using initializeApp()\nconst db = getFirestore();\nconnectFirestoreEmulator(db, '127.0.0.1', 8080);https://github.com/firebase/snippets-web/blob/467eaa165dcbd9b3ab15711e76fa52237ba37f8b/snippets/firestore-next/emulator-suite/fs_emulator_connect.js#L8-L12\n```\n\n### Web version 8\n\n| [Learn\nmore](//firebase.google.com/docs/web/learn-more#modular-version) about the tree-shakeable modular Web API and its advantages over the namespaced API. \n\n```javascript\n// Firebase previously initialized using firebase.initializeApp().\nvar db = firebase.firestore();\nif (location.hostname === \"localhost\") {\n db.useEmulator(\"127.0.0.1\", 8080);\n}https://github.com/firebase/snippets-web/blob/467eaa165dcbd9b3ab15711e76fa52237ba37f8b/firestore/emulator-suite.js#L6-L10\n```\n\nThe Firestore in Native Mode emulator clears database contents when shut down. Since\nthe offline cache of the Firestore SDK is not automatically cleared, you may\nwant to disable local persistence in your emulator configuration to avoid\ndiscrepancies between the emulated database and local caches; in the Web SDK,\npersistence is disabled by default.\n\nClear emulator data\n-------------------\n\nThe Firestore emulator includes a REST endpoint for deleting all\nthe data currently in the emulator. You can use this endpoint to clear data\nbetween tests without shutting down the emulator.\n\nTo delete all data in the emulator, perform an HTTP `DELETE` operation against\nthe following endpoint, replacing \u003cvar translate=\"no\"\u003eHOST\u003c/var\u003e and \u003cvar translate=\"no\"\u003ePORT\u003c/var\u003e with the\nhost and port you selected and replacing \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e with your\nown project ID: \n\n http://\u003cvar translate=\"no\"\u003eHOST\u003c/var\u003e:\u003cvar translate=\"no\"\u003ePORT\u003c/var\u003e/emulator/v1/projects/\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e/databases/(default)/documents\n\nAdjust the host and port if the emulator does not use `127.0.0.1:8080`.\nYour code should await REST confirmation that the deletion finished or failed.\n\nYou can perform this operation from the shell using `curl`: \n\n $ curl -v -X DELETE \"http://\u003cvar translate=\"no\"\u003eHOST\u003c/var\u003e:\u003cvar translate=\"no\"\u003ePORT\u003c/var\u003e/emulator/v1/projects/\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e/databases/(default)/documents\"\n\nHow the Firestore emulator differs from production\n--------------------------------------------------\n\nThe Firestore emulator attempts to faithfully replicate the\nbehavior of the production service with some notable limitations.\n\n### Transactions\n\nThe emulator doesn't attempt to mimic the transaction behavior that's seen in\nproduction. It uses a simple locking approach and doesn't attempt to mirror\nthe various concurrency modes offered in the production environment.\n\nWhen you're testing features that involve multiple concurrent writes to one\ndocument, the emulator might be slow to complete write requests. It might take\nup to 30 seconds for the emulator to release the locks. If you need to adjust\nthe test timeout intervals, then do so.\n\nThe emulator doesn't also attempt to mimic all of the\n[production limits](/firestore/quotas#writes_and_transactions), such as\ntimeouts \\& size limits, which involve transactions. If you test features that\ndepend on these production limits, then we recommend that you use a production\nenvironment instead of an emulator.\n\n### Indexes\n\nThe emulator does not track composite indexes and will instead execute any\nvalid query. Make sure to test your app against a real Firestore\ninstance to determine which indexes you require.\n\n### Limits\n\nThe emulator does not enforce all limits enforced in production. For example,\nthe emulator may allow transactions that would be rejected as too large by the\nproduction service. Make sure you are familiar with the\n[documented limits](/firestore/docs/quotas) and that you design your app to\nproactively avoid them."]]
