Skip to content
Switch branches/tags


Failed to load latest commit information.
Latest commit message
Commit time


Ruby library

CircleCI Gem Version codecov

Quickstart installation

Add the gem to your Gemfile and run bundle install:

gem "remove_bg"

Or run gem install remove_bg to install globally.

Please note the base configuration has the following resolution limits:

Output format Resolution limit
PNG 10 megapixels
JPG 25 megapixels

Full installation

For best performance and quality the gem requires an image processing library. Please install one of the following libraries:

The gem will auto-detect any image processing libraries present. However you may prefer to explicitly configure which library to use:

RemoveBg.configure do |config|
  config.image_processor = :minimagick # For ImageMagick or GraphicsMagick
  # or
  config.image_processor = :vips

The full installation has the following resolution limits:

Output format Resolution limit
PNG 25 megapixels
JPG 25 megapixels
ZIP 25 megapixels


For more in-depth documentation please see RubyDoc

Configuring an API key

To configure a global API key (used by default unless overridden per request):

RemoveBg.configure do |config|
  config.api_key = "<api-key>"

It's not recommended to commit your API key to version control. You may want to read the API key from an environment variable (e.g. ENV.fetch("REMOVE_BG_API_KEY")) or find an alternative method.

Removing the background from an image

Currently the gem supports removing the background from a file or a URL:


Request options

The processing options outlined in the API reference can be specified per request:

RemoveBg.from_file("image.png", size: "hd", type: "product", channels: "rgba")

The API key can also be specified per request:

RemoveBg.from_file("image.png", api_key: "<api-key>")

Handling the result

Background removal requests return a result object which includes the processed image data and the metadata about the operation.

result = RemoveBg.from_file("image.png")             # => "\x89PNG..."
result.height           # => 333
result.width            # => 500
result.credits_charged  # => 1.0

There's also a #save convenience method:"processed/image.png")"image.png", overwrite: true) # Careful!

Producing transparent images over 10 megapixels

After configuring a full installation (detailed above) you can process images over 10 megapixels with a transparent output.

Process images with either the png or zip format. If you specify the zip format it's possible to save the archive and handle composition yourself.

result = RemoveBg.from_file("large-image.jpg", format: "zip")"result-with-transparency.png")
# or
result.save_zip("") # If you want to handle composition yourself

Rate limits

The API has rate limits. Image processing results include the rate limit information:

result = RemoveBg.from_file("image.jpg")
# => <RateLimit reset_at='2020-05-20T12:00:00Z' total=500 remaining=499 retry_after_seconds=nil>

If you exceed the rate limit a RemoveBg::RateLimitError exception will be raised. This also contains further information via the #rate_limit method.

Fetching account information

To display the account information for the currently configured API key:

account = RemoveBg.account_info # If an API key is set via RemoveBg.configuration
# or
account = RemoveBg.account_info(api_key: "<api_key>")

account.api.free_calls # => 50  # => 200



The gem is available as open source under the terms of the MIT License.


Bug reports and pull requests are welcome on GitHub at remove-bg/ruby.



After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests.

Releasing a new version

To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to


To preview the YARD documentation locally run:

bundle exec yard server --reload
open http://localhost:8808/


Official ruby gem for the API





No packages published