Ruby HTTP client based on libcurl
C Ruby
Latest commit 158fcc1 Sep 5, 2016 @toland Release version 0.8.0
Failed to load latest commit information.
ext/patron Fix the ifdefs being swapped Jul 10, 2016
lib Release version 0.8.0 Sep 5, 2016
script Allow manual startup of the test server Nov 18, 2011
spec Fix specs, and encoding issue for headers. Aug 11, 2016
.autotest For some reason autotest wasn't catching changes properly. Jan 19, 2009
.gitignore Add YARD, replace RDoc task Apr 10, 2016
.rspec New build system and rspec upgrade Dec 31, 2010
.travis.yml Use Random to generate payloads in the test Jul 18, 2016
.yardopts Rework charset coercion Aug 11, 2016 Up the version number to 0.8 (we are introducing features) Aug 19, 2016
Gemfile Revert request action to be a symbol, but still allow upcase and down… Jul 24, 2014
Gemfile.lock Release version 0.8.0 Sep 5, 2016
LICENSE Added license file. Jun 23, 2009
Rakefile Add YARD, replace RDoc task Apr 10, 2016
patron.gemspec Delete a stray quote May 29, 2016
pic.png do not convert body encoding if it's not a text Nov 11, 2011

Patron is a Ruby HTTP client library based on libcurl. It does not try to expose the full "power" (read complexity) of libcurl but instead tries to provide a sane API while taking advantage of libcurl under the hood.


First, you instantiate a Session object. You can set a few default options on the Session instance that will be used by all subsequent requests:

sess =
sess.timeout = 10
sess.base_url = ""
sess.headers['User-Agent'] = 'myapp/1.0'

You can set options with a hash in the constructor:

sess ={ :timeout => 10,
                             :base_url => '',
                             :headers => {'User-Agent' => 'myapp/1.0'} } )

Or the set options in a block:

sess = do |patron|
    patron.timeout = 10
    patron.base_url = ''
    patron.headers = {'User-Agent' => 'myapp/1.0'}

Output debug log:

sess.enable_debug "/tmp/patron.debug"

The Session is used to make HTTP requests.

resp = sess.get("/foo/bar")

Requests return a Response object:

if resp.status < 400
  puts resp.body

The GET, HEAD, PUT, POST and DELETE operations are all supported.

sess.put("/foo/baz", "some data")

You can ship custom headers with a single request:"/foo/stuff", "some data", {"Content-Type" => "text/plain"})

Known issues

Currently, an issue is at play with OSX builds of curl which use Apple's SecureTransport. Such builds (which Patron is linking to), are causing segfaults when performing HTTPS requests in forked subprocesses. If you need to check whether your system is affected, run the Patron test suite by performing

$ bundle install && bundle exec rspec

in the Patron install directory. Most default curl configurations on OSX (both the Apple-shipped version and the version available via Homebrew) are linked to SecureTransport and are likely to be affected. This issue may also manifest in forking webserver implementations (such as Unicorn or Passenger) and in forking job execution engines (such as resque), so even though you may not be using fork() directly your server engine might be doing it for you.

To circumvent the issue, you need to build curl with OpenSSL via homebrew. When doing so, curl will use openssl as it's SSL driver. You also need to change the Patron compile flag:

$ brew install curl --with-openssl && \
    gem install patron --with-curl-config=/usr/local/opt/curl/bin/curl-config

You can also save this parameter for all future Bundler-driven gem installs by setting this flag in Bundler proper:

$ bundle config build.patron --with-curl-config=/usr/local/opt/curl/bin/curl-config


By itself, the Patron::Session objects are not thread safe (each Session holds a single curl_state pointer during the request/response cycle). At this time, Patron has no support for curl_multi_* family of functions for doing concurrent requests. However, the actual code that interacts with libCURL does unlock the RVM GIL, so using multiple Session objects in different threads is possible with a high degree of concurrency. For sharing a resource of sessions between threads we recommend using the excellent connection_pool gem by Mike Perham.

patron_pool = 5, timeout: 5) { }
patron_pool.with do |session|


Patron uses encoding features of Ruby, so you need at least Ruby 1.9. Also, a recent version of libCURL is required. We recommend at least 7.19.4 because it supports limiting the protocols, and that is very important for security - especially if you follow redirects.

On OSX the provided libcurl is sufficient. You will have to install the libcurl development packages on Debian or Ubuntu. Other Linux systems are probably similar. For Windows we do not have an established build instruction at the moment, unfortunately.


sudo gem install patron

Copyright (c) 2008 The Hive