Typhoeus sets a form content type on POST only, and the docs make you fix the rest yourself
Typhoeus wraps libcurl in order to make fast and reliable requests.
At a glance
- What is it?
- typhoeus/typhoeus wraps a native HTTP library in Ruby so that requests can be issued serially or in parallel through one interface. The sharp edge is small and specific: the convenience methods set a form content type automatically on POST and on nothing else, so a form-encoded PUT needs the header set by hand.
- Who is it for?
- Typhoeus suits a Ruby service that needs to fan out many HTTP requests, that wants its HTTP layer to be a native library rather than a pure-Ruby socket implementation, and that is comfortable reading the three classes the library exposes rather than a large option surface. It suits anyone streaming a large response to disk, because the body callback stops the library holding the whole thing in memory.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly Ruby, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- typhoeus/typhoeus4,138 ★ · +5
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| typhoeus/typhoeus | 4.1k | 4.1k |
5 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Three classes, and the third is the one you will spend your time in
The interface is three classes and the readme states what each one is. A request object represents an HTTP request. A response object represents what came back. A hydra manages making parallel connections. Everything else in the library is convenience on top of those three. A request is built with a URL and a set of options, and the readme is careful that the options are all optional, with the method defaulting to a GET. Two option names are easy to confuse and the documentation separates them explicitly: one is for parameters in the URL, the other is for the request body, and if you want a form-encoded body you must use the body form rather than the params form. That distinction is the most common source of confusion when moving from another HTTP client, and it is stated in a sentence rather than a table.
Parallelism is two steps you write yourself, not a flag
Running requests in parallel means building a hydra, queueing requests onto it, and then running it. The run call blocks and returns once everything queued has finished. There is no timeout parameter on the run call in the documented usage, and there is no promise about concurrency limits in the examples, so anything about tuning the pool size has to come from the API documentation rather than the readme. What the examples do show is the pattern people actually need: queueing a request from inside the completion callback of another one, so a third request is built from the result of the first. That is the reason to use a hydra rather than a thread pool, because the sequencing logic stays in one place instead of being spread across threads. It is also the point where care is needed, since a callback that queues unconditionally can build an unbounded chain.
Callbacks fire when the request finishes, so registering late is a bug
The error handling example carries a warning that is easy to skim and expensive to learn the hard way. The callbacks are executed right after the request is finished, which means you must define them before running the request. The example itself shows the correct order: build the request, attach the completion handler, then run it. The handler shown is also the reference for how failures are distinguished, and the distinction is not one. There is a check for a successful response, a separate check for a timeout, and a separate branch for a response code of zero, which the comment explains as meaning no HTTP response was obtained at all and the transport's own message is worth logging. Only after those three is a non-successful HTTP status treated as an HTTP failure. Four cases, four different things to do, and the transport-level case is the one most wrappers hide.
Form encoding is automatic on POST and manual everywhere else
One behaviour is worth isolating because it will cost you an afternoon if you do not know it. When using POST, the content type is set automatically to form encoding. That is not true for any other method, including PUT, PATCH and HEAD, and that remains the case whether you pass a body or not. To get the same effect as POST on those verbs, where a hash in the body arrives as parameters at the receiving end, you have to set the header yourself and pass the body as a hash. The documented example does exactly that, with the header spelled out and the body as a two-key hash. So the rule is short enough to remember: one verb is magic, and every other verb is your responsibility. There is no configuration to make it uniform.
Streaming replaces the body, and interruption has a documented protocol
For a large response, attaching a body callback switches the library into streaming mode, yielding chunks as they are read instead of storing the whole thing. The consequence is stated in the example's own comment: once the body has been streamed, the response's body is an empty string. Any code that inspects the body after streaming has to read the file it wrote instead. The example also shows the headers callback, which is the place to bail out early: it checks the status and raises if it is not success, so a large download fails before writing anything. Interrupting partway through has its own documented mechanism: return a specific symbol from the body callback, which stops the stream properly and avoids the memory leak that interrupting with an exception would cause. Three ways to stop, one of which is correct.
Proxies take two options, one of them a colon-separated credential
Proxy support is two options on the request. The first is the proxy address, and the second, used only when the proxy needs credentials, is a colon-separated username and password. The documentation compares that form to a basic authentication option elsewhere in the library, which is a useful pointer because it tells you the credential is not being passed as a hash but as a single string. That matters if your password contains a colon, since nothing in the documentation says how that case is handled. Both options are set on the request rather than globally in the examples shown, so a client with mixed traffic needs to build options per request rather than configuring a default proxy. The readme does not describe a global default here, so whether one exists is a question for the API documentation.
Two install commands, and a repository that keeps its upgrade notes separately
Installation is the pair of commands you would expect from a library meant to live in a bundle:
bundle add typhoeusand, if you are installing the published package directly rather than through a bundle:
gem install typhoeusThe project tracks its documentation on an external service generated from the master branch rather than shipping a versioned copy in the repository, which means the docs always describe the newest code. The repository layout matches a mature library rather than a small one: a spec directory with its configuration, a separate directory of performance scripts, a guardfile for running specs on change, a rakefile, a gemfile, a changelog, and a file specifically about upgrading. That last file is the one to read first if you are coming from an older version, because option names in a wrapper around a native library are exactly the kind of thing that moves between versions.
Editorial conclusion
Typhoeus suits a Ruby service that needs to fan out many HTTP requests, that wants its HTTP layer to be a native library rather than a pure-Ruby socket implementation, and that is comfortable reading the three classes the library exposes rather than a large option surface. It suits anyone streaming a large response to disk, because the body callback stops the library holding the whole thing in memory. It does not suit a caller who expects symmetric behaviour across HTTP verbs, since form encoding is automatic on one verb only. It also does not suit code that wants the parallelism abstracted away entirely, because queueing and running are separate steps you must write yourself. Before adopting it, remember that callbacks fire immediately after a request finishes so they must be registered first, set the content type explicitly on any verb other than POST when sending a form, and return the documented symbol rather than an exception if you need to interrupt a stream cleanly.
Frequently asked questions
What is Typhoeus in Greek mythology?
The name in this library comes from the mythical beast with a hundred serpent heads, and the readme compares the library to a modern code version of it: many requests, one managed object. The three classes are named after that idea, with the hydra being the multi-headed manager of parallel connections.
How do I install Typhoeus?
Run `bundle add typhoeus` to add it to a project's dependencies, or `gem install typhoeus` to install the published package directly. The library wraps a native HTTP library, so a system build of that library may be required in addition to the gem.
How does Typhoeus run requests in parallel?
Create a hydra, queue requests onto it, and call run, which blocks until everything queued has completed. You can also queue a new request from inside the completion callback of another one, which is how a later request can be built from an earlier result. Both serial and parallel requests return a response object.
Why does my Typhoeus PUT request not arrive as form data?
Because the form content type is set automatically only on POST. For PUT, PATCH, HEAD and the other verbs you have to set the content type header yourself and pass the body as a hash, which is what the documented example does. The params option is for the URL and is not the same thing as a form-encoded body.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/typhoeus-typhoeus)Star history chart for your README
[](https://hysenlabs.com/projects/typhoeus-typhoeus)Was this useful?