Delete subscriptions

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

Caution: Deletion is permanent. Once deleted, subscriptions cannot be restored.

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

Before you begin

Required roles and permissions

To get the permissions that you need to delete a subscription, ask youradministrator to grant you thePub/Sub Editor(roles/pubsub.editor) IAM role on yoursubscription or project that contains the subscription.

This predefined role contains the permissions required to delete a subscription.To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

  • pubsub.subscriptions.delete
  • pubsub.subscriptions.list
    • This permission is only required when deleting subscriptions usingthe Google Cloud console.

You might also be able to get these permissions withothercustom roles orpredefined Pub/Sub roles.

Delete subscriptions

Console

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

    Go to Subscriptions

  2. Select the subscription to delete.
  3. ClickDelete.

gcloud

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

    Activate Cloud Shell

    At the bottom of the Google Cloud console, aCloud 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 thegcloud pubsub subscriptions delete command:

    gcloudpubsubsubscriptionsdeleteSUBSCRIPTION_ID

REST

To delete a subscription, use theprojects.subscriptions.deletemethod:

Request:

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

DELETE https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_IDAuthorization: BearerACCESS_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 forother processes to see its effect.

C++

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

namespacepubsub_admin=::google::cloud::pubsub_admin;namespacepubsub=::google::cloud::pubsub;[](pubsub_admin::SubscriptionAdminClientclient,std::stringconst&project_id,std::stringconst&subscription_id){autostatus=client.DeleteSubscription(pubsub::Subscription(project_id,subscription_id).FullName());// Note that kNotFound is a possible result when the library retries.if(status.code()==google::cloud::StatusCode::kNotFound){std::cout <<"The subscription was not found\n";return;}if(!status.ok())throwstd::runtime_error(status.message());std::cout <<"The subscription was successfully deleted\n";

C#

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

usingGoogle.Cloud.PubSub.V1;publicclassDeleteSubscriptionSample{publicvoidDeleteSubscription(stringprojectId,stringsubscriptionId){SubscriberServiceApiClientsubscriber=SubscriberServiceApiClient.Create();SubscriptionNamesubscriptionName=SubscriptionName.FromProjectSubscription(projectId,subscriptionId);subscriber.DeleteSubscription(subscriptionName);}}

Go

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

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

import("context""fmt""io""cloud.google.com/go/pubsub/v2""cloud.google.com/go/pubsub/v2/apiv1/pubsubpb")funcdelete(wio.Writer,projectID,subIDstring)error{// projectID := "my-project-id"// subID := "my-sub"ctx:=context.Background()client,err:=pubsub.NewClient(ctx,projectID)iferr!=nil{returnfmt.Errorf("pubsub.NewClient: %w",err)}deferclient.Close()req:=&pubsubpb.DeleteSubscriptionRequest{Subscription:fmt.Sprintf("projects/%s/subscriptions/%s",projectID,subID),}iferr:=client.SubscriptionAdminClient.DeleteSubscription(ctx,req);err!=nil{returnfmt.Errorf("Delete: %w",err)}fmt.Fprintf(w,"Subscription %q deleted.",subID)returnnil}

Java

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

importcom.google.api.gax.rpc.NotFoundException;importcom.google.cloud.pubsub.v1.SubscriptionAdminClient;importcom.google.pubsub.v1.SubscriptionName;importjava.io.IOException;publicclassDeleteSubscriptionExample{publicstaticvoidmain(String...args)throwsException{// TODO(developer): Replace these variables before running the sample.StringprojectId="your-project-id";StringsubscriptionId="your-subscription-id";deleteSubscriptionExample(projectId,subscriptionId);}publicstaticvoiddeleteSubscriptionExample(StringprojectId,StringsubscriptionId)throwsIOException{try(SubscriptionAdminClientsubscriptionAdminClient=SubscriptionAdminClient.create()){SubscriptionNamesubscriptionName=SubscriptionName.of(projectId,subscriptionId);try{subscriptionAdminClient.deleteSubscription(subscriptionName);System.out.println("Deleted subscription.");}catch(NotFoundExceptione){System.out.println(e.getMessage());}}}}

Node.js

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

/***TODO(developer):Uncommentthisvariablebeforerunningthesample.*///constsubscriptionNameOrId='YOUR_SUBSCRIPTION_NAME_OR_ID';//ImportstheGoogleCloudclientlibraryconst{PubSub}=require('@google-cloud/pubsub');//Createsaclient;cachethisforfurtheruseconstpubSubClient=newPubSub();asyncfunctiondeleteSubscription(subscriptionNameOrId){//DeletesthesubscriptionawaitpubSubClient.subscription(subscriptionNameOrId).delete();console.log(`Subscription${subscriptionNameOrId}deleted.`);}

Node.ts

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

/***TODO(developer):Uncommentthisvariablebeforerunningthesample.*///constsubscriptionNameOrId='YOUR_SUBSCRIPTION_NAME_OR_ID';//ImportstheGoogleCloudclientlibraryimport{PubSub}from'@google-cloud/pubsub';//Createsaclient;cachethisforfurtheruseconstpubSubClient=newPubSub();asyncfunctiondeleteSubscription(subscriptionNameOrId:string){//DeletesthesubscriptionawaitpubSubClient.subscription(subscriptionNameOrId).delete();console.log(`Subscription${subscriptionNameOrId}deleted.`);}

PHP

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

use Google\Cloud\PubSub\PubSubClient;/** * Creates a Pub/Sub subscription. * * @param string $projectId  The Google project ID. * @param string $subscriptionName  The Pub/Sub subscription name. */function delete_subscription($projectId, $subscriptionName){    $pubsub = new PubSubClient([        'projectId' => $projectId,    ]);    $subscription = $pubsub->subscription($subscriptionName);    $subscription->delete();    printf('Subscription deleted: %s' . PHP_EOL, $subscription->name());}

Python

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

fromgoogle.cloudimportpubsub_v1# TODO(developer)# project_id = "your-project-id"# subscription_id = "your-subscription-id"subscriber=pubsub_v1.SubscriberClient()subscription_path=subscriber.subscription_path(project_id,subscription_id)# Wrap the subscriber in a 'with' block to automatically call close() to# close the underlying gRPC channel when done.withsubscriber:subscriber.delete_subscription(request={"subscription":subscription_path})print(f"Subscription deleted:{subscription_path}.")

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, seethe deprecated code samples.

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

# subscription_id = "your-subscription-id"pubsub=Google::Cloud::PubSub.newsubscription_admin=pubsub.subscription_adminsubscription_admin.delete_subscription\subscription:pubsub.subscription_path(subscription_id)puts"Subscription#{subscription_id} deleted."

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

What's next

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

Last updated 2026-02-19 UTC.