Delete subscriptions

You can delete Pub/Sub subscriptions with the Google Cloud console, Google Cloud CLI, client library, or Pub/Sub API.

This document discusses how to delete subscriptions in Pub/Sub.

Before you begin

Required roles and permissions

To get the permission that you need to delete a subscription, ask your administrator to grant you the Pub/Sub Editor (roles/pubsub.editor) IAM role on the subscription. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the pubsub.subscriptions.delete permission, which is required to delete a subscription.

You might also be able to get this permission with custom roles or other predefined roles.

Console

  1. In the Google Cloud console, go to the Subscriptions page.

    Go to Subscriptions

  2. Select the subscription to delete.
  3. Click Delete.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. To delete a subscription, run the gcloud pubsub subscriptions delete command:

    gcloud pubsub subscriptions delete SUBSCRIPTION_ID

REST

To delete a subscription, use the projects.subscriptions.delete method:

Request:

The request must be authenticated with an access token in the Authorization header. To obtain an access token for the current Application Default Credentials: gcloud auth application-default print-access-token.

DELETE https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer ACCESS_TOKEN

Where:

  • PROJECT_ID is your project ID.
  • SUBSCRIPTION_ID is your subscription ID.

Response:

If the request is successful, the response is an empty JSON object.

Delete is an eventually consistent operation, so it might take time for other processes to see its effect.

C++

Before trying this sample, follow the C++ setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C++ API reference documentation.

C#

Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C# API reference documentation.

Go

The following sample uses the major version of the Go Pub/Sub client library (v2). If you are still using the v1 library, see the migration guide to v2. To see a list of v1 code samples, see the deprecated code samples.

Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation.

Java

Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation.

Node.js

Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation.

Node.ts

Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation.

PHP

Before trying this sample, follow the PHP setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub PHP API reference documentation.

Python

Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Python API reference documentation.

Ruby

The following sample uses Ruby Pub/Sub client library v3. If you are still using the v2 library, see the migration guide to v3. To see a list of Ruby v2 code samples, see the deprecated code samples.

Before trying this sample, follow the Ruby setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Ruby API reference documentation.

You can create a subscription with the same name as the one that you just deleted. However, the newly created subscription is entirely independent of the previously deleted one. Messages that are intended for the old subscription are not delivered to the new subscription.

What's next

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-03-20 UTC.