carrierwaveuploader /carrierwave

Classier solution for file uploads for Rails, Sinatra and other Ruby web frameworks

★ 8,763⑂ 1,641👁 127⑃ 913● 1,909▤ 43
下载:3.1.43.1.4 ↓3.1.42026-08-30
-1
日增长
8,763
stars
1,641
forks
127
watchers
913
prs
1,909
issues
43
releases

README

CarrierWave

This gem provides a simple and extremely flexible way to upload files from Ruby applications.
It works well with Rack based web applications, such as Ruby on Rails.






 Information

 RDoc documentation available on RubyDoc.info
 Source code available on GitHub
 More information, known limitations, and how-tos available on the wiki

 Getting Help

 Please ask the community on Stack Overflow for help if you have any questions. Please do not post usage questions on the issue tracker.
 Please report bugs on the issue tracker but read the "getting help" section in the wiki first.

 Installation

Install the latest release:


$ gem install carrierwave


In Rails, add it to your Gemfile:

ruby
gem 'carrierwave', '~ 3.0'


Finally, restart the server to apply the changes.

 Supported Ruby and Rails versions

Each release is tested against the versions below. The gemspec only states a
minimum, so Bundler will happily install an old CarrierWave alongside a Rails
newer than it has ever seen — which is how a patch-level upgrade ends up failing
at boot. Check this table when upgrading Rails.

| CarrierWave | Rails      | Ruby     |
|-------------|------------|----------|
| 4.0         | 7.0 – 8.1  | = 2.7   |
| 3.1         | 6.0 – 8.0  | = 2.5   |
| 3.0         | 6.0 – 7.1  | = 2.5   |
| 2.2         | 5.0 – 6.1  | = 2.2.2 |

Only the latest release gets fixes; older lines are listed so you can tell
whether your combination was ever supported.

 Upgrading from 2.x or earlier

CarrierWave 3.0 comes with a change in the way of handling the file extension on conversion. This results in following issues if you use process convert: :format to change the file format:

- If you have it on the uploader itself (not within a version), the file extension of the cached file will change. That means if you serve both CarrierWave 2.x and 3.x simultaneously on the same workload (e.g. using blue-green deployment), a cache file stored by 2.x can't be retrieved by 3.x and vice versa.
- If you have it within a version, the file extension of the stored file will change. You need to perform recreate_versions! to make it usable again.

To preserve the 2.x behavior, you can set force_extension false right after calling process convert: :format. See 2659 for the detail.

 Getting Started

Start off by generating an uploader:

	rails generate uploader Avatar

this should give you a file in:

	app/uploaders/avatar_uploader.rb

Check out this file for some hints on how you can customize your uploader. It
should look something like this:

ruby
class AvatarUploader  '/url/to/file.png'
u.avatar.current_path  = 'path/to/file.png'
u.avatar_identifier  = 'file.png'


Note: u.avatar will never return nil, even if there is no photo associated to it.
To check if a photo was saved to the model, use u.avatar.file.nil? instead.

 DataMapper, Mongoid, Sequel

Other ORM support has been extracted into separate gems:

 carrierwave-datamapper
 carrierwave-mongoid
 carrierwave-sequel

The

Top issues

Latest release

3.1.4 v3.1.4 2026-08-30
Added
 Support for marcel 2.x (@mshibuya 214f309)

 Changed
 Relax the marcel dependency constraint (@mkon 2828)
 Relax the image_processing dependency to allow ~ 2.0 (@amiryalsa 2826)

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON