This functionality provided by this module is now part of mechanize. I don't intend to make further standalone releases of ClientCookie.

Please read this note explaining the relationship between ClientCookie, cookielib and urllib2, and which to use when.

ClientCookie is a Python module for handling HTTP cookies on the client side, useful for accessing web sites that require cookies to be set and then returned later. It also provides some other (optional) useful stuff: HTTP-EQUIV and Refresh handling, automatic adding of the Referer [sic] header, automatic observance of robots.txt and lazily-seek()able responses. These extras are implemented using an extension that makes it easier to add new functionality to urllib2. It has developed from a port of Gisle Aas' Perl module HTTP::Cookies, from the libwww-perl library.

 import ClientCookie
 response = ClientCookie.urlopen("")

This function behaves identically to urllib2.urlopen, except that it deals with cookies automatically. That's probably all you need to know.

Python 2.0 or above is required, and urllib2 is recommended. If you have 2.1 or above, you've already got a recent enough version of urllib2. For Python 2.0, you need the newer versions from Python 2.1 (available from the source distribution or Python CVS: Note that you don't need to replace the original urllib2 / urllib - you can just make sure they're in sys.path ahead of the copies from 2.0's standard library.

For full documentation, see here and the docstrings in the module source code.

Other than Gisle, particular thanks to Johnny Lee (MSIE Perl code) and Ronald Tschalar (advice on Netscape cookies).

Notes about ClientCookie, urllib2 and cookielib

Even if you're not using Python 2.4, please note the last of these points.

  1. The cookie handling parts of ClientCookie are in Python 2.4 standard library as module cookielib and extensions to module urllib2.
  2. ClientCookie works with Python 2.4.
  3. For new code to run on Python 2.4, I recommend use of standard library modules urllib2 and cookielib instead of ClientCookie. I recommend turning on RFC 2965 support to work around a bug in cookielib in Python 2.4.0.
  4. Handler classes thst are missing from 2.4's urllib2 (eg. HTTPRefreshProcessor) may be used with 2.4's urllib2 (however, note the paragraph below). With any version of Python, parts of urllib2 that are missing from ClientCookie (eg. ProxyHandler) may be used with ClientCookie, and urllib2.Request objects may be used with ClientCookie. IMPORTANT: For all other code, use ClientCookie exclusively: do NOT mix use of ClientCookie and urllib2!

Finally, note that, if you want to use ClientCookie.RefreshProcessor with Python 2.4's urllib2, you must also use ClientCookie.HTTPRedirectHandler.


All documentation (including these web pages) is included in the distribution.

To port your code from 0.4.x to 1.0.x, see here.

Stable release.

Old release.

For installation instructions, see the INSTALL file included in the distribution.


The Subversion (SVN) trunk is, so to check out the source:

svn co ClientCookie

FAQs - pre-install

I prefer questions and comments to be sent to the mailing list rather than direct to me.

John J. Lee, May 2006.