{"id":23780,"library":"gcloud-storage-emulator","title":"Google Cloud Storage Emulator","description":"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.","status":"active","version":"0.5.0","language":"python","source_language":"en","source_url":"https://github.com/fsd/gsutil","tags":["gcs","emulator","testing","google-cloud-storage"],"install":[{"cmd":"pip install gcloud-storage-emulator","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"The emulator mimics the google-cloud-storage client; your code imports from google.cloud.storage.","package":"google-cloud-storage","optional":false}],"imports":[{"note":"The package name uses underscores, not hyphens or dots. Common mistake: treating the dashed name as a module path.","wrong":"from gcloud_storage.emulator import Emulator","symbol":"Emulator","correct":"from gcloud_storage_emulator import Emulator"}],"quickstart":{"code":"from gcloud_storage_emulator import Emulator\nimport os\n\n# Start the emulator on port 9023\nemu = Emulator(port=9023)\nstarted = emu.start()\n\n# Point the client to the emulator\nos.environ['STORAGE_EMULATOR_HOST'] = 'http://localhost:9023'\n\n# Use google-cloud-storage client as usual\nfrom google.cloud import storage\nclient = storage.Client()\n\n# List buckets (will be empty)\nbuckets = list(client.list_buckets())\nprint(buckets)\n\nemu.stop()","lang":"python","description":"Start the emulator, set environment variable, and use google-cloud-storage client."},"warnings":[{"fix":"If you need persistence, consider using a different emulator (e.g., fake-gcs-server) or implement your own storage backend.","message":"The emulator does not persist data. All data is stored in memory and lost when the emulator stops.","severity":"gotcha","affected_versions":"all"},{"fix":"Set os.environ['STORAGE_EMULATOR_HOST'] = 'http://localhost:9023' before instantiating storage.Client().","message":"The environment variable STORAGE_EMULATOR_HOST must be set before creating the google-cloud-storage client. Otherwise, the client will connect to actual GCS.","severity":"gotcha","affected_versions":"all"},{"fix":"Use Emulator(port=9023) instead of Emulator(host='localhost:9023').","message":"The Emulator class constructor signature changed in 0.4.0: the 'port' parameter replaced the old 'host' parameter.","severity":"deprecated","affected_versions":"0.4.0+"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Import using underscores: from gcloud_storage_emulator import Emulator","cause":"Installed the package with hyphens but imported with hyphens or dots.","error":"ModuleNotFoundError: No module named 'gcloud_storage_emulator'"},{"fix":"Set os.environ['STORAGE_EMULATOR_HOST'] = 'http://localhost:9023' before creating storage.Client().","cause":"Forgot to set STORAGE_EMULATOR_HOST environment variable before creating the client.","error":"<google.cloud.storage.client.Client object at 0x...> bucket: ... (but it connects to real GCS)"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}