Listing Amazon S3 buckets - Amazon Simple Storage Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Listing Amazon S3 buckets

To return a list of general purpose buckets that you own, you can use ListBuckets. You can list your buckets by using the Amazon S3 console, the Amazon Command Line Interface, or the Amazon SDKs. For ListBuckets requests using the Amazon CLI, Amazon SDKs, and Amazon S3 REST API, Amazon Web Services accounts that use the default service quota for buckets (10,000 buckets), support both paginated and unpaginated requests. Regardless of how many buckets you have in your account, you can create page sizes between 1 and 10,000 buckets to list all of your buckets. For paginated requests, ListBuckets requests return both the bucket names and the corresponding Amazon Web Services Regions for each bucket. The following Amazon Command Line Interface and Amazon SDK examples show you how to use pagination in your ListBuckets request. Note that some Amazon SDKs assist with pagination.

Permissions

To list all of your buckets, you must have the s3:ListAllMyBuckets permission. If you're encountering an HTTP Access Denied (403 Forbidden) error, see Troubleshoot access denied (403 Forbidden) errors in Amazon S3.

Important

We strongly recommend using only paginated ListBuckets requests. Unpaginated ListBuckets requests are only supported for Amazon Web Services accounts set to the default general purpose bucket quota of 10,000. If you have an approved general purpose bucket quota above 10,000, you must send paginated ListBuckets requests to list your account’s buckets. All unpaginated ListBuckets requests will be rejected for Amazon Web Services accounts with a general purpose bucket quota greater than 10,000.

  1. Sign in to the Amazon Web Services Management Console and open the Amazon S3 console at https://console.amazonaws.cn/s3/.

  2. In the left navigation pane, choose Buckets.

  3. On the General purpose buckets tab, you can see a list of your general purpose buckets.

  4. To find buckets by name, enter a bucket name in the search box.

To use the Amazon CLI to generate a listing of general purpose buckets, you can use the ls or list-buckets commands. The following examples show you how to create a paginated list-buckets request and an unpaginated ls request. To use these examples, replace the user input placeholders.

Example – List all the buckets in your account by using ls (unpaginated)

The following example command lists all the general purpose buckets in your account in a single non-paginated call. This call returns a list of all buckets in your account (up to 10,000 results):

$ aws s3 ls

For more information and examples, see List bucket and objects.

Example – List all the buckets in your account by using ls (paginated)

The following example command makes one or more paginated calls to list all the general purpose buckets in your account, returning 100 buckets per page:

$ aws s3 ls --page-size 100

For more information and examples, see List bucket and objects.

Example – List all the buckets in your account (paginated)

The following example provides a paginated list-buckets command to list all the general purpose buckets in your account. The --max-items and --page-size options limit the number of buckets listed to 100 per page. 

$ aws s3api list-buckets /
    --max-items 100 / 
    --page-size 100

If the number of items output (--max-items) is fewer than the total number of items returned by the underlying API calls, the output includes a continuation token, specified by the starting-token argument, that you can pass to a subsequent command to retrieve the next set of items. The following example shows how to use the starting-token value returned by the previous example. You can specify the starting-code to retrieve the next 100 buckets. 

$ aws s3api list-buckets / 
    --max-items 100 / 
    --page-size 100 /
    --starting-token eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==

Example – List all the buckets in an Amazon Web Services Region (paginated)

The following example command uses the --bucket-region parameter to list up to 100 buckets in an account that are in the us-east-2 Region. Requests made to a Regional endpoint that is different from the value specified in the --bucket-region parameter are not supported. For example, if you want to limit the response to your buckets in us-east-2, you must make your request to an endpoint in us-east-2.

$ aws s3api list-buckets /
    --region us-east-2 /
    --max-items 100 / 
    --page-size 100 /
    --bucket-region us-east-2

Example – List all the buckets that begin with a specific bucket name prefix (paginated)

The following example command lists up to 100 buckets that have a name starting with the amzn-s3-demo-bucket prefix. 

$ aws s3api list-buckets /
    --max-items 100 /
    --page-size 100 /
    --prefix amzn-s3-demo-bucket

The following examples show you how to list your general purpose buckets by using the Amazon SDKs

SDK for Python
Example – ListBuckets request (paginated)
import boto3

s3 = boto3.client('s3')
response = s3.list_buckets(MaxBuckets=100)
Example – ListBuckets response (paginated)
import boto3

s3 = boto3.client('s3')
response = s3.list_buckets(MaxBuckets=1,ContinuationToken="eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==EXAMPLE--")
SDK for Java
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.Bucket;
import com.amazonaws.services.s3.model.ListBucketsPaginatedRequest;
import com.amazonaws.services.s3.model.ListBucketsPaginatedResult;

import java.util.List;

public class ListBuckets {
    public static void main(String[] args) {
        final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
        ListBucketsPaginatedRequest listBucketsPaginatedRequest = new ListBucketsPaginatedRequest().withMaxBuckets(1);
        ListBucketsPaginatedResult listBucketsPaginatedResult = s3.listBuckets(listBucketsPaginatedRequest);
        List<Bucket> buckets = listBucketsPaginatedResult.getBuckets();
        System.out.println("Your Amazon S3 buckets are:");
        for (Bucket b : buckets) {
            System.out.println("* " + b.getName() + " region: " + b.getRegion());
        }
        System.out.println("continuation token: " + listBucketsPaginatedResult.getContinuationToken());
    }
}
SDK for Java 2.x
import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.Bucket;
import software.amazon.awssdk.services.s3.model.ListBucketsRequest;
import software.amazon.awssdk.services.s3.model.ListBucketsResponse;

import java.util.List;

public class ListBuckets {
    public static void main(String[] args) {
        // Create an S3 client
        S3Client s3 = S3Client.builder()
                .region(Region.US_EAST_1) // Replace with your preferred region
                .credentialsProvider(DefaultCredentialsProvider.create())
                .build();

        try {
            // List buckets
            ListBucketsRequest listBucketsRequest = ListBucketsRequest.builder()
                    .maxBuckets(10)
                    .build();
            ListBucketsResponse listBucketsResponse = s3.listBuckets(listBucketsRequest);
            List<Bucket> buckets = listBucketsResponse.buckets();

            // Print bucket names
            System.out.println("Your Amazon S3 buckets are:");
            for (Bucket bucket : buckets) {
                System.out.println(bucket.name());
                System.out.println(bucket.getBucketRegion());
            }

        } catch (Exception e) {
            System.err.println("Error listing buckets: " + e.getMessage());
            e.printStackTrace();
        } finally {
            // Close the S3 client to release resources
            s3.close();
        }
    }
}
SDK for Go
package main
import (
 "context"
 "fmt"
 "log"
 "github.com/aws/aws-sdk-go-v2/aws"
 "github.com/aws/aws-sdk-go-v2/config"
 "github.com/aws/aws-sdk-go-v2/service/s3"
)
func main() {
 cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion("us-east-2"))
 if err != nil {
  log.Fatal(err)
 }
 client := s3.NewFromConfig(cfg)
 maxBuckets := 1000
 resp, err := client.ListBuckets(context.TODO(), management portals3.ListBucketsInput{MaxBuckets: aws.Int32(int32(maxBuckets))})
 if err != nil {
  log.Fatal(err)
 }
 fmt.Println("S3 Buckets:")
 for _, bucket := range resp.Buckets {
     fmt.Println("- Name:", *bucket.Name)
     fmt.Println("-BucketRegion", *bucket.BucketRegion)
 }
 fmt.Println(resp.ContinuationToken == nil)
 fmt.Println(resp.Prefix == nil)
}