Listing Amazon S3 buckets - Amazon Simple Storage Service

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 AWS Command Line Interface, or the AWS SDKs. For ListBuckets requests using the AWS CLI, AWS SDKs, and Amazon S3 REST API, AWS 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 AWS Regions for each bucket. The following AWS Command Line Interface and AWS SDK examples show you how to use pagination in your ListBuckets request. Note that some AWS 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 AWS 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 AWS accounts with a general purpose bucket quota greater than 10,000.

  1. Sign in to the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/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 AWS 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 AWS 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 AWS 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)
}