Library for accessing S3 objects and buckets, supports EU and US buckets
Latest commit 172b4c6 Oct 19, 2016 @qoobaa bumped ruby



Build Status

S3 library provides access to Amazon’s Simple Storage Service.

It supports all S3 regions through the REST API.


gem install s3


Initialize the service

require "s3"
service = => "...",
                          :secret_access_key => "...")
#=> #<S3::Service:...>

List buckets

#=> [#<S3::Bucket:first-bucket>,
#    #<S3::Bucket:second-bucket>]

Find bucket

first_bucket = service.buckets.find("first-bucket")
#=> #<S3::Bucket:first-bucket>


first_bucket = service.bucket("first-bucket")
#=> #<S3::Bucket:first-bucket>

service.bucket("first-bucket") does not check whether a bucket with the name "first-bucket" exists, but it also does not issue any HTTP requests. Thus, the second example is much faster than buckets.find. You can use first_bucket.exists? to check whether the bucket exists after calling service.bucket.

Create bucket

new_bucket ="newbucketname") => :eu)

Remember that bucket name for EU can't include “_” (underscore).

Please refer to: for more information about bucket name restrictions.

List objects in a bucket

#=> [#<S3::Object:/first-bucket/lenna.png>,
#    #<S3::Object:/first-bucket/lenna_mini.png>]

Find object in a bucket

object = first_bucket.objects.find("lenna.png")
#=> #<S3::Object:/first-bucket/lenna.png>

Access object metadata (cached from find)

#=> "image/png"

Access object content (downloads the object)

#=> "\x89PNG\r\n\x1A\n\x00\x00\x00\rIHDR\x00..."

Delete an object

#=> true

Create an object

new_object ="bender.png")
#=> #<S3::Object:/synergy-staging/bender.png>

new_object.content = open("bender.png")

new_object.acl = :public_read
#=> true

Please note that new objects are created with “private” ACL by default.

Request access to a private object

Returns a temporary url to the object that expires on the timestamp given. Defaults to one hour expire time.

new_object.temporary_url( + 1800)

Fetch ACL

object = bucket.objects.find('lenna.png')
object.request_acl # or bucket.request_acl

This will return hash with all users/groups and theirs permissions

Modify ACL

object = bucket.objects.find("lenna.png")
object.copy(:key => "lenna.png", :bucket => bucket, :acl => :public_read)

Upload file direct to amazon

Rails 3

Check the example in this gist, which describes how to use a simple form element to upload files directly to S3.

See also


Copyright © 2009 Jakub Kuźma, Mirosław Boruta. See LICENSE for details.