Check out what’s new from Firebase@ Google I/O 2021, and join our alpha program for early access to the new Remote Config personalization feature. Learn more

Connect your app to the Cloud Storage Emulator

Before connecting your app to the Cloud Storage emulator, make sure that you understand the overall Firebase Local Emulator Suite workflow, and that you install and configure the Local Emulator Suite and review its CLI commands.

Choose a Firebase project

The Firebase Local Emulator Suite emulates products for a single Firebase project.

To select the project to use, before you start the emulators, in the CLI run firebase use in your working directory. Or, you can pass the --project flag to each emulator command.

Local Emulator Suite supports emulation of real Firebase projects and demo projects.

Project type Features Use with emulators
Real A real project is one you configured and activated in the Firebase console; a real project has live resources, like databases, storage buckets, functions or any other resource you set up for that project. When working with real projects, you can run emulators for any or all of the supported products in your project.

For any products you are not emulating, your apps and code will interact with the live database, storage bucket, function, etc.
Demo A demo project has no Firebase console configuration and no live resources.

Demo project IDs have the demo- prefix.
When working with demo projects, your apps and code interact with emulators only. If your app interacts 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

Android, iOS, and Web SDKs

Set up your in-app configuration or test classes to interact with the Cloud Storage emulator as follows.

FirebaseStorage.getInstance().useEmulator('', 9199);
iOS - Swift"localhost", port:9199)
Web v8
var storage =;
storage.useEmulator("localhost", 9199);
Web v9 (Beta)
import { getStorage, useStorageEmulator } from "firebase/storage";

const storage = getStorage();
useStorageEmulator(storage, "localhost", 9199);

No additional setup is needed to test Cloud functions triggered by Cloud Storage events using the emulator. When the Cloud Storage and Cloud Functions emulators are both running, they automatically work together.

Admin SDKs

The Firebase Admin SDKs automatically connect to the Cloud Storage emulator when the FIREBASE_STORAGE_EMULATOR_HOST environment variable is set:

export FIREBASE_STORAGE_EMULATOR_HOST="localhost:9199"

Note that the Cloud Functions emulator is automatically aware of the Cloud Storage emulator so you can skip this step when testing integrations between Cloud Functions and Cloud Storage emulators. The environment variable will be automatically set for the Admin SDK in Cloud Storage.

When connecting to the Cloud Storage emulator from any other environment, you will need to specify a project ID. You can pass a project ID to initializeApp directly or set the GCLOUD_PROJECT environment variable. Note that you do not need to use your real Firebase project ID; the Cloud Storage emulator will accept any project ID, as long as it has a valid format.

Node.js Admin SDK
admin.initializeApp({ projectId: "your-project-id" });
Environment Variable
export GCLOUD_PROJECT="your-project-id"

Import and export data

The database and Cloud Storage emulators 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.

firebase emulators:export ./dir

In tests, on emulator startup, import the baseline data.

firebase emulators: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 --import flag.

firebase emulators:start --import=./dir --export-on-exit

These data import and export options work with the firebase emulators:exec command as well. For more, refer to the emulator command reference.


The Cloud Storage Emulator attempts to faithfully replicate the behavior of the production service with some notable limitations:

  • Using the Admin SDK, only uploading files, downloading files, and modifying file metadata are supported. Other functionality provided by Google Cloud Storage client libraries is not yet available.

What next?