Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Python HTTP library with thread-safe connection pooling, file post support, sanity friendly, and more.
Python Other
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



 * Re-use the same socket connection for multiple requests
   (``HTTPConnectionPool`` and ``HTTPSConnectionPool``) (with client-side certificates)
 * File posting (``encode_multipart_formdata``)
 * Built-in redirection and retries (optional)
 * Supports gzip and deflate (big thanks to niphlod)
 * Thread-safe
 * Small and easy to understand codebase perfect for extending and building upon. For a more comprehensive alternative, have a look at `httplib2 <>`_.

What's wrong with urllib and urllib2?

There are two critical features missing from the Python standard library:
Connection re-using/pooling and file posting. It's not terribly hard to
implement these yourself, but it's much easier to use a module that already
did the work for you.

The Python standard libraries ``urllib`` and ``urllib2`` have little to do
with each other. They were designed to be independent and standalone, each
solving a different scope of problems, and ``urllib3`` follows in a similar

Why do I want to reuse connections?

Performance. When you normally do a urllib call, a separate socket
connection is created with each request. By reusing existing sockets
(supported since HTTP 1.1), the requests will take up less resources on the
server's end, and also provide a faster response time at the client's end.
With some simple benchmarks (see `test/
), downloading 15 URLs from is about twice as fast when using
HTTPConnectionPool (which uses 1 connection) than using plain urllib (which
uses 15 connections).

This library is perfect for:

 * Talking to an API
 * Crawling a website
 * Any situation where being able to post files, handle redirection, and
   retrying is useful. It's relatively lightweight, so it can be used for


Go to the `Examples wiki <>`_
for more nice syntax-highlighted examples.

But, long story short::

  import urllib3

  API_URL = ''

  http_pool = urllib3.connection_from_url(API_URL)

  fields = {'v': '1.0', 'q': 'urllib3'}
  r = http_pool.get_url(API_URL, fields)

  print r.status,

Run the tests

First we need to install ``nose`` and ``webob``, then add the
source directory to your PYTHONPATH, then run ``nosetests``.

    $ pip install nose webob
    $ cd patch/to/urllib3
    $ python develop
    $ nosetests

Some tests require the ```` running to pass.

    $ python -O test/
    $ nosetests



 * Open an issue to start a discussion around a feature or a bug.
 * Write a fix, attach a patch to the issue.
 * Write a test which shows that the bug was fixed or that the feature works
   as expected. Attach patch for the test to the issue.
 * Bug the author until it gets merged and published. :) Make sure to include
   what information you want added to the ``CONTRIBUTORS.txt`` if any.
Something went wrong with that request. Please try again.