Google Cloud Storage Emulator

0.5.0 verified Fri May 01 auth: no python

A stub emulator for the Google Cloud Storage API, useful for testing and development without connecting to real GCS. Current version 0.5.0, supports Python 3.6+. Release cadence is sporadic.

pip install gcloud-storage-emulator

Common errors

error ModuleNotFoundError: No module named 'gcloud_storage_emulator' ↓

cause Installed the package with hyphens but imported with hyphens or dots.

fix

Import using underscores: from gcloud_storage_emulator import Emulator

error <google.cloud.storage.client.Client object at 0x...> bucket: ... (but it connects to real GCS) ↓

cause Forgot to set STORAGE_EMULATOR_HOST environment variable before creating the client.

fix

Set os.environ['STORAGE_EMULATOR_HOST'] = 'http://localhost:9023' before creating storage.Client().

Warnings

gotcha The emulator does not persist data. All data is stored in memory and lost when the emulator stops. ↓

fix If you need persistence, consider using a different emulator (e.g., fake-gcs-server) or implement your own storage backend.

gotcha The environment variable STORAGE_EMULATOR_HOST must be set before creating the google-cloud-storage client. Otherwise, the client will connect to actual GCS. ↓

fix Set os.environ['STORAGE_EMULATOR_HOST'] = 'http://localhost:9023' before instantiating storage.Client().

deprecated The Emulator class constructor signature changed in 0.4.0: the 'port' parameter replaced the old 'host' parameter. ↓

fix Use Emulator(port=9023) instead of Emulator(host='localhost:9023').

Imports

Emulator
wrong
```
from gcloud_storage.emulator import Emulator
```
correct
```
from gcloud_storage_emulator import Emulator
```
The package name uses underscores, not hyphens or dots. Common mistake: treating the dashed name as a module path.

Quickstart

Start the emulator, set environment variable, and use google-cloud-storage client.

from gcloud_storage_emulator import Emulator
import os

# Start the emulator on port 9023
emu = Emulator(port=9023)
started = emu.start()

# Point the client to the emulator
os.environ['STORAGE_EMULATOR_HOST'] = 'http://localhost:9023'

# Use google-cloud-storage client as usual
from google.cloud import storage
client = storage.Client()

# List buckets (will be empty)
buckets = list(client.list_buckets())
print(buckets)

emu.stop()