Library for accessing S3 objects and buckets, supports EU and US buckets
Branch: master
Clone or download
Latest commit 2c1960a Jun 22, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin updated for ruby >2.4 Jan 9, 2018
lib bumped version Jun 22, 2018
test Issue 125: Object#content now aware of @content initilization May 11, 2018
.gitignore updated for ruby >2.4 Jan 9, 2018
.travis.yml updated for ruby >2.4 Jan 9, 2018 updated for ruby >2.4 Jan 9, 2018
Gemfile updated for ruby >2.4 Jan 9, 2018
Gemfile.lock updated gemfile lock Jun 22, 2018
LICENSE.txt updated for ruby >2.4 Jan 9, 2018
README.rdoc Update README Aug 19, 2016
Rakefile updated for ruby >2.4 Jan 9, 2018
s3.gemspec fixed on new ruby Jan 11, 2018



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.