carrierwaveuploader /carrierwave
Classier solution for file uploads for Rails, Sinatra and other Ruby web frameworks
★ 8,763⑂ 1,641👁 127⑃ 913● 1,909▤ 43
-1
Daily
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
#2768Error: wrong number of arguments (given 1, expected 4) for Ruby 3.23 comments · 2024-12-23#2782Reuploading an attachment with a different file name allowed in newer versions.2 comments · 2025-03-21#2324Support for background jobs out of the box2 comments · 2018-06-28#2832Can we get a new release?0 comments · 2026-10-12#2272Custom validation response on whitelists?0 comments · 2018-01-25#2245Instrumentation and monitoring0 comments · 2017-11-03#1820Migrate Cucumber features to specs0 comments · 2016-01-02
Latest release
3.1.4 v3.1.4 2026-08-30Added 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)