Pub/Sub emulator

Pub/Sub is asynchronous messaging between publishers and subscribers. Topics decouple event producers from the applications that process those events.

When to use Pub/Sub

Typical uses

Use when several consumers need to react to the same event independently of its publisher. Consumers acknowledge completed work and handle retries without blocking the producer.

Examples

Event-driven application pipelines
Background processing and fan-out

Example usage

Service ID: pubsub. Starts by default. Use an already running LocalCloud runtime for the examples below.

Export the local project and mapped endpoints in your client process, then use the client settings below. First-time setup

# Export GOOGLE_CLOUD_PROJECT and PUBSUB_EMULATOR_HOST
eval "$(localcloud env)"

REST gateway examples use the generated HTTP address in SERVICE_USAGE_EMULATOR_HOST; native SDKs can use a different protocol.

Python

Publish and acknowledge a message

Send, receive, and acknowledge an event; Pub/Sub lets producers and consumers work independently.

A repeatable topic, subscription, publish, and pull example.

SDK dependencies

Run in a new example directory

python3 -m venv .venv
source .venv/bin/activate
python -m pip install google-cloud-pubsub

Save as hello.py

import os
from uuid import uuid4
from google.cloud import pubsub_v1

assert os.environ['PUBSUB_EMULATOR_HOST']
project = os.environ['GOOGLE_CLOUD_PROJECT']
publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
name = 'hello-' + uuid4().hex[:12]
topic = publisher.topic_path(project, name)
subscription = subscriber.subscription_path(project, name)

publisher.create_topic(request={'name': topic}, timeout=30)
try:
    subscriber.create_subscription(request={'name': subscription, 'topic': topic}, timeout=30)
    try:
        publisher.publish(topic, b'Hello, Pub/Sub!').result(timeout=30)
        response = subscriber.pull(request={'subscription': subscription, 'max_messages': 1}, timeout=30)
        assert response.received_messages
        for received in response.received_messages:
            print(received.message.data.decode())
            subscriber.acknowledge(request={'subscription': subscription, 'ack_ids': [received.ack_id]}, timeout=30)
    finally:
        subscriber.delete_subscription(request={'subscription': subscription}, timeout=30)
finally:
    publisher.delete_topic(request={'topic': topic}, timeout=30)
    subscriber.close()
    publisher.transport.close()

Run the example

python hello.py

Verify the result

The command completes successfully and prints the expected output shown below.

Expected output

Hello, Pub/Sub!

Full example guide

Java

Create a topic and publish a message

Publish a message to a new topic; Pub/Sub lets producers send events independently of their consumers.

Java needs an explicit plaintext channel and no-credentials provider. Requires JDK 17+ and Maven.

SDK dependencies

Run in a new example directory

cat > pom.xml <<'XML'
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>example</groupId><artifactId>local-example</artifactId><version>1</version>
  <dependencies><dependency>
    <groupId>com.google.cloud</groupId><artifactId>google-cloud-pubsub</artifactId><version>1.157.0</version>
  </dependency></dependencies>
</project>
XML
mvn -q dependency:build-classpath -Dmdep.outputFile=classpath.txt

Save as Hello.java

import com.google.api.gax.core.NoCredentialsProvider;
import com.google.api.gax.grpc.GrpcTransportChannel;
import com.google.api.gax.rpc.FixedTransportChannelProvider;
import com.google.cloud.pubsub.v1.*;
import com.google.protobuf.ByteString;
import com.google.pubsub.v1.*;
import io.grpc.ManagedChannelBuilder;
import java.util.Objects;
import java.util.UUID;
import java.util.concurrent.TimeUnit;

public class Hello {
  public static void main(String[] args) throws Exception {
    var host = Objects.requireNonNull(System.getenv("PUBSUB_EMULATOR_HOST"));
    var project = Objects.requireNonNull(System.getenv("GOOGLE_CLOUD_PROJECT"));
    var channel = ManagedChannelBuilder.forTarget(host).usePlaintext().build();
    var transport = FixedTransportChannelProvider.create(GrpcTransportChannel.create(channel));
    var credentials = NoCredentialsProvider.create();
    var settings = TopicAdminSettings.newBuilder()
        .setTransportChannelProvider(transport).setCredentialsProvider(credentials).build();
    try (var topics = TopicAdminClient.create(settings)) {
      var topic = TopicName.of(project, "example-" + UUID.randomUUID());
      topics.createTopic(topic);
      try {
        var publisher = Publisher.newBuilder(topic)
            .setChannelProvider(transport).setCredentialsProvider(credentials).build();
        try {
          var message = PubsubMessage.newBuilder()
              .setData(ByteString.copyFromUtf8("Hello from LocalCloud!")).build();
          System.out.println(publisher.publish(message).get(30, TimeUnit.SECONDS));
        } finally {
          publisher.shutdown();
          publisher.awaitTermination(30, TimeUnit.SECONDS);
        }
      } finally {
        topics.deleteTopic(topic);
      }
    } finally {
      channel.shutdownNow();
    }
  }
}

Run the example

java --class-path "$(cat classpath.txt)" Hello.java

Verify the result

Publishing returns a message ID, and the finally block deletes the temporary topic. This checks publishing; use the Python or gcloud example to verify subscriber delivery.

gcloud CLI

Publish and pull a message

Publish, pull, and acknowledge a message; Pub/Sub decouples event producers from background consumers.

gcloud uses the gateway REST endpoint, while SDKs use PUBSUB_EMULATOR_HOST.

Configure gcloud CLI

: "${SERVICE_USAGE_EMULATOR_HOST:?Export the LocalCloud environment first}"
export CLOUDSDK_CORE_PROJECT="${GOOGLE_CLOUD_PROJECT:?Export the LocalCloud environment first}"
export CLOUDSDK_AUTH_DISABLE_CREDENTIALS=true
export CLOUDSDK_API_ENDPOINT_OVERRIDES_PUBSUB="${SERVICE_USAGE_EMULATOR_HOST%/}/"

Run in your terminal

(
set -e
TOPIC="example-$(date +%s)-$$"
SUBSCRIPTION="$TOPIC-sub"
gcloud pubsub topics create "$TOPIC"
trap 'gcloud pubsub topics delete "$TOPIC" --quiet' EXIT
gcloud pubsub subscriptions create "$SUBSCRIPTION" --topic="$TOPIC"
trap 'gcloud pubsub subscriptions delete "$SUBSCRIPTION" --quiet; gcloud pubsub topics delete "$TOPIC" --quiet' EXIT
gcloud pubsub topics publish "$TOPIC" --message="Hello from LocalCloud!"
gcloud pubsub subscriptions pull "$SUBSCRIPTION" --auto-ack --limit=1
)

Verify the result

The pulled message contains Hello from LocalCloud!. The trap removes the subscription and topic on exit; verify the message contents before treating the test as successful.

Verify a resource workflow by creating isolated state, performing the operation, and reading the result back. Run cleanup even after a failure; delete only test-owned resources.

Connection failed? Check localcloud status --verbose, enabled services, and client exports. Stop accidental Google Cloud calls; correct local routing before retrying.

Documented workflows

Topics, subscriptions, push/pull, StreamingPull, and acknowledgements

Create a topic and subscription, publish a fixture, and receive it through pull, StreamingPull, or push. Acknowledge successful work and check how the consumer handles an expired acknowledgment deadline.
Attribute filters, dead-letter forwarding, and retries

Publish events with matching and nonmatching attributes to test subscription filters. Make a handler fail, then inspect retries and dead-letter forwarding instead of treating publication as delivery proof.
Retention, snapshots, and timestamp/snapshot seek

Create a snapshot before acknowledging test messages, then seek to the snapshot or a retained timestamp. Verify which messages are delivered again and use the new acknowledgment IDs.
Avro/Protobuf schemas, revisions, and JSON/binary validation

Register an Avro or Protobuf schema and its revisions, then publish valid and invalid JSON or binary payloads. Assert that invalid batches fail before the consumer receives them.
Wrapped and unwrapped push payloads with optional metadata headers

Configure noWrapper to deliver raw message bytes and enable writeMetadata when the receiver needs message headers. Test the default wrapped JSON path separately from unwrapped delivery.
Expiration and message-storage policy configuration readback

Set subscription expirationPolicy and topic messageStoragePolicy, then read them back over the API and after restart. These settings support configuration tests; they do not expire subscriptions or relocate messages locally.
Authenticated push with locally signed OIDC tokens

Configure an OIDC service account and audience on a push subscription. Have the receiver validate the locally signed bearer token against the LocalCloud issuer and JWKS before accepting the message.

Service boundaries

No exactly-once delivery, message ordering, export subscriptions, or transforms
Push receivers must trust the local issuer/JWKS; retry and retention timing is approximate
Expiration and storage policies are metadata; stored IAM does not enforce publish or topic deletion

Code examples and integrations

Integration

Build an integration test loop

Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Open guide

Google Cloud

Official SDK code samples

Browse language-specific samples. Adapt endpoints and use the local workflows listed above.

Browse official samples

Agent testing

Use Pub/Sub with an AI agent

Before the agent changes application logic, have it create local Pub/Sub state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

Pub/Sub local test

Use LocalCloud to test Pub/Sub locally. Read https://local.cloud/ai/agents.md, set PUBSUB_EMULATOR_HOST=localhost:5383, create a topic and subscription, publish one test message, pull or stream it, ack it, and verify the payload without using real GCP credentials.

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

Agent resources has more prompts and the AGENTS.md template.

Pub/Sub emulator FAQ

How do I run Pub/Sub locally?

Start LocalCloud using the setup guide, then export its environment in the same terminal as your application.

Which environment variable points the SDK at the local Pub/Sub?

LocalCloud exports PUBSUB_EMULATOR_HOST=localhost:5383. Use the generated value, because the CLI picks another port when the default is in use. Some SDKs also need explicit client endpoint options; the variable alone does not route them locally.

Does the local Pub/Sub behave exactly like Google Cloud?

No. LocalCloud runs the documented workflows on this page within the service boundaries listed here. Validate behavior against real Pub/Sub before production deployment.

Related guides

Compatibility: compare all 27 service guides.
Configuration: service selection and runtime settings.
Official Pub/Sub documentation : service concepts and cloud usage.

Pub/Sub emulator

Typical uses

Explore another service

Example usage

Python

Publish and acknowledge a message

Save as hello.py

Run the example

Verify the result

Expected output

Java

Create a topic and publish a message

Save as Hello.java

Run the example

Verify the result

gcloud CLI

Publish and pull a message

Configure gcloud CLI

Run in your terminal

Verify the result

Documented workflows

Topics, subscriptions, push/pull, StreamingPull, and acknowledgements

Attribute filters, dead-letter forwarding, and retries

Retention, snapshots, and timestamp/snapshot seek

Avro/Protobuf schemas, revisions, and JSON/binary validation

Wrapped and unwrapped push payloads with optional metadata headers

Expiration and message-storage policy configuration readback

Authenticated push with locally signed OIDC tokens

Service boundaries

Code examples and integrations

Build an integration test loop

Official SDK code samples

Use Pub/Sub with an AI agent

Pub/Sub local test

Pub/Sub emulator FAQ

How do I run Pub/Sub locally?

Which environment variable points the SDK at the local Pub/Sub?

Does the local Pub/Sub behave exactly like Google Cloud?

Related guides