Created: 2008-07-15 15:31
Updated: 2019-02-26 08:13
License: other


Curb - Libcurl bindings for Ruby Build Status

Curb (probably CUrl-RuBy or something) provides Ruby-language bindings for the libcurl(3), a fully-featured client-side URL transfer library. cURL and libcurl live at .

Curb is a work-in-progress, and currently only supports libcurl's 'easy' and 'multi' modes.


Curb is copyright (c)2006 Ross Bamford, and released under the terms of the Ruby license. See the LICENSE file for the gory details.

You will need

  • A working Ruby installation (2.1+)
  • A working (lib)curl installation, with development stuff (7.5+, tested with 7.19.x)
  • A sane build environment (e.g. gcc, make)


... will usually be as simple as:

$ gem install curb

On Windows, make sure you're using the DevKit and the development version of libcurl. Unzip, then run this in your command line (alter paths to your curl location, but remember to use forward slashes):

gem install curb --platform=ruby -- --with-curl-lib=C:/curl-7.39.0-devel-mingw32/lib --with-curl-include=C:/curl-7.39.0-devel-mingw32/include

Or, if you downloaded the archive:

$ rake compile && rake install

If you have a weird setup, you might need extconf options. In this case, pass them like so:

$ rake compile EXTCONF_OPTS='--with-curl-dir=/path/to/libcurl --prefix=/what/ever' && rake install

Curb is tested only on GNU/Linux x86 and Mac OSX - YMMV on other platforms. If you do use another platform and experience problems, or if you can expand on the above instructions, please report the issue at

On Ubuntu, the dependencies can be satisfied by installing the following packages:

$ sudo apt-get install libcurl3 libcurl3-gnutls libcurl4-openssl-dev

On RedHat:

$ sudo yum install ruby-devel libcurl-devel openssl-devel

Curb has fairly extensive RDoc comments in the source. You can build the documentation with:

$ rake doc

Usage & examples

Curb provides two classes:

  • Curl::Easy - simple API, for day-to-day tasks.
  • Curl::Multi - more advanced API, for operating on multiple URLs simultaneously.

To use either, you will need to require the curb gem:

require 'curb'

Super simple API (less typing)

http = Curl.get("")
puts http.body_str

http ="", {:foo => "bar"})
puts http.body_str

http = Curl.get("") do |http|
  http.headers['Cookie'] = 'foo=1;bar=2'
puts http.body_str

Simple fetch via HTTP:

c = Curl::Easy.perform("")
puts c.body_str

Same thing, more manual:

c ="")
puts c.body_str

Additional config:

Curl::Easy.perform("") do |curl|
  curl.headers["User-Agent"] = "myapp-0.0"
  curl.verbose = true

Same thing, more manual:

c ="") do |curl|
  curl.headers["User-Agent"] = "myapp-0.0"
  curl.verbose = true


HTTP basic authentication:

c ="")
c.http_auth_types = :basic
c.username = 'foo'
c.password = 'bar'

HTTP "insecure" SSL connections (like curl -k, --insecure) to avoid Curl::Err::SSLCACertificateError:

c ="")
c.ssl_verify_peer = false

Supplying custom handlers:

c ="")

c.on_body { |data| print(data) }
c.on_header { |data| print(data) }


Reusing Curls:

c =

["", ""].map do |url|
  c.url = url


c = Curl::Easy.http_post("",
                         Curl::PostField.content('thing[name]', 'box'),
                         Curl::PostField.content('thing[type]', 'storage'))

HTTP POST file upload:

c ="")
c.multipart_form_post = true
c.http_post(Curl::PostField.file('thing[file]', 'myfile.rb'))

Using HTTP/2

c ="")
c.set(:HTTP_VERSION, Curl::HTTP_2_0)

puts (c.body_str.include? "You are using HTTP/2 right now!") ? "HTTP/2" : "HTTP/1.x"

Multi Interface (Basic HTTP GET):

# make multiple GET requests
easy_options = {:follow_location => true}
# Use Curl::CURLPIPE_MULTIPLEX for HTTP/2 multiplexing
multi_options = {:pipeline => Curl::CURLPIPE_HTTP1}

Curl::Multi.get(['url1','url2','url3','url4','url5'], easy_options, multi_options) do|easy|
  # do something interesting with the easy response
  puts easy.last_effective_url

Multi Interface (Basic HTTP POST):

# make multiple POST requests
easy_options = {:follow_location => true, :multipart_form_post => true}
multi_options = {:pipeline => Curl::CURLPIPE_HTTP1}

url_fields = [
  { :url => 'url1', :post_fields => {'f1' => 'v1'} },
  { :url => 'url2', :post_fields => {'f1' => 'v1'} },
  { :url => 'url3', :post_fields => {'f1' => 'v1'} }
], easy_options, multi_options) do|easy|
  # do something interesting with the easy response
  puts easy.last_effective_url

Multi Interface (Advanced):

responses = {}
requests = ["", ""]
m =
# add a few easy handles
requests.each do |url|
  responses[url] = ""
  c = do|curl|
    curl.follow_location = true
    curl.on_body{|data| responses[url] << data; data.size }
    curl.on_success {|easy| puts "success, add more easy handles" }

m.perform do
  puts "idling... can do some work here"

requests.each do|url|
  puts responses[url]

Easy Callbacks

  • on_success is called when the response code is 2xx
  • on_redirect is called when the response code is 3xx
  • on_missing is called when the response code is 4xx
  • on_failure is called when the response code is 5xx
  • on_complete is called in all cases.
Cookies help us deliver our services. By using our services, you agree to our use of cookies Learn more