Nov 18, 20265 min read

Google Pub/Sub Emulator: Test Topics and Subscriptions Locally

Install and start the Pub/Sub emulator, point the client libraries at it with PUBSUB_EMULATOR_HOST, create topics and subscriptions on startup, and know which production features it does not cover.

Illustration for Google Pub/Sub Emulator: Test Topics and Subscriptions Locally

Google Cloud Pub/Sub has an official emulator, which puts it ahead of most managed queues for local development, but it is a Java process installed through the gcloud CLI that starts empty every time, listens on IPv6 localhost by default, and only takes effect when every client in every process sees the PUBSUB_EMULATOR_HOST variable.

Forget the variable in one terminal and that worker quietly publishes to the cloud project.

This guide covers installing and starting the emulator, creating topics and subscriptions on startup, the client code, and the features the emulator does not reproduce.

Pub/Sub emulator at a glance

Encore Pub/SubPub/Sub emulatorReal Pub/Sub in a dev project
How it startsWith encore rungcloud beta emulators pubsub startAlways on
Client configurationNonePUBSUB_EMULATOR_HOST in every processCredentials and project ID
Topics and subscriptionsDeclared in code, created automaticallyCreated every session by a script or the appTerraform, gcloud or console
IAMEncore provisions access per service on deployNot supportedEnforced
Exactly-once deliveryTopic setting, applied on deployNot in the supported listSupported on pull subscriptions
CostNone locallyNoneBilled usage

Install and start the emulator

The emulator ships as a gcloud component and needs a JDK. The project ID can be any string; it does not have to exist.

~
$ gcloud components install pubsub-emulator$ gcloud beta emulators pubsub start --project=local-dev --host-port=127.0.0.1:8085[pubsub] This is the Pub/Sub fake.[pubsub] Implementation may be incomplete or differ from the real system.[pubsub] INFO: Server started, listening on 8085# in every other terminal that runs your code$ $(gcloud beta emulators pubsub env-init)$ echo $PUBSUB_EMULATOR_HOST127.0.0.1:8085

Per the emulator docs, it listens on IPv6 ::1 by default, so pass --host-port=127.0.0.1:8085 if IPv6 is disabled or a container needs to reach it. In Docker Compose, run the Google Cloud CLI image with its emulators tag, which includes the Pub/Sub emulator, and set PUBSUB_EMULATOR_HOST=pubsub:8085 on the app container.

Create topics and subscriptions on startup

Resources and messages only live as long as the emulator session. The usual pattern is an idempotent setup step that runs when the app starts locally, tolerating "already exists" errors.

// pubsub-setup.ts import { PubSub } from "@google-cloud/pubsub"; // The client library reads PUBSUB_EMULATOR_HOST and skips credentials. const pubsub = new PubSub({ projectId: process.env.GOOGLE_CLOUD_PROJECT ?? "local-dev" }); async function ensure(topicName: string, subName: string) { const [topic] = await pubsub.topic(topicName).get({ autoCreate: true }); const sub = topic.subscription(subName); const [exists] = await sub.exists(); if (!exists) await topic.createSubscription(subName, { ackDeadlineSeconds: 30 }); } export async function setupLocalPubSub() { if (!process.env.PUBSUB_EMULATOR_HOST) return; // never create resources in a real project here await ensure("order-placed", "reserve-stock"); }

The guard matters: without it, a developer who forgot the variable runs the setup against the cloud project with their own credentials. The subscriber side is the normal client code, sub.on("message", ...) with message.ack() once the work is done.

What the emulator supports and what it does not

Google lists publishing, push and pull subscriptions, ordering, replay, dead-letter topics, retry policies, Avro schemas and filtering as supported. The known limitations are UpdateTopic and UpdateSnapshot, IAM operations, configurable retention (all messages are kept indefinitely), subscription expiration, protocol buffer schemas, BigQuery delivery, seek to a timestamp on ordered subscriptions, and Single Message Transforms. Exactly-once delivery is not in the supported list. Push endpoints can be plain http against the emulator, while production requires https, so a push handler that works locally can still fail on certificate or authentication setup.

IAM is the biggest gap, since locally every client can publish and subscribe to everything, so a missing roles/pubsub.subscriber binding on the production service account only shows up after deploy, which is covered in Google Cloud Pub/Sub basics and the push vs pull guide.

Encore Pub/Sub under encore run

Encore

Encore brings infrastructure from code to the services that publish and consume, and the topic and subscription are declared next to the handler instead of in a setup script. encore run runs Pub/Sub in memory, with no emulator process, JDK or PUBSUB_EMULATOR_HOST. On deploy to your own GCP project, Encore provisions Google Cloud Pub/Sub topics and subscriptions, with dead-lettering for failed messages, and provisions an IAM role for the service, or a service account on GCP. On AWS the same code uses SNS and SQS.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

// orders/orders.ts import { api } from "encore.dev/api"; import { Topic, Subscription, Attribute } from "encore.dev/pubsub"; export interface OrderEvent { orderId: Attribute<string>; status: "placed" | "paid" | "shipped"; } export const orderEvents = new Topic<OrderEvent>("order-events", { deliveryGuarantee: "at-least-once", orderingAttribute: "orderId", }); export const markPaid = api( { expose: true, method: "POST", path: "/orders/:orderId/paid" }, async ({ orderId }: { orderId: string }) => { await orderEvents.publish({ orderId, status: "paid" }); }, ); const _ = new Subscription(orderEvents, "notify-customer", { handler: async (event) => { // Send the email. Keep this idempotent: messages can be redelivered. }, });

Under encore run, calling the endpoint publishes the event and the subscriber runs in the same local trace in the development dashboard. One difference from the emulator: the orderingAttribute has no effect in local environments, so ordering is only enforced after deploy, where each ordering key is delivered in publish order.

A coding agent can add a topic and subscriber, then call the endpoint locally to watch the message arrive, without a setup script that has to stay in sync with the production topics.

Best fit: TypeScript or Go services on GCP that want local Pub/Sub on every developer machine and the production topics and subscriptions created from the same declarations.

Which one to use

If the code calls Pub/Sub directly through the Google client libraries, the emulator is the official way to test it locally; add the guard around resource creation and a smoke test against a real dev project for IAM and exactly-once. If the topics connect parts of a TypeScript or Go backend, Encore Pub/Sub removes the emulator and the environment variable and provisions the same topics on deploy.

Frequently asked questions

How do I run the Google Pub/Sub emulator?

Install it with gcloud components install pubsub-emulator, start it with gcloud beta emulators pubsub start --project=any-id, then run $(gcloud beta emulators pubsub env-init) so PUBSUB_EMULATOR_HOST points the client libraries at localhost:8085. Topics and subscriptions start empty every session, so create them from your app or a setup script.

What does the Pub/Sub emulator not support?

Google's documentation lists UpdateTopic and UpdateSnapshot, IAM operations, configurable message retention, subscription expiration, protocol buffer schemas, BigQuery delivery, seek to a timestamp on ordered subscriptions and Single Message Transforms as unsupported. Exactly-once delivery is not in its list of supported features either, so test it against a real subscription.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders