Read the v2.0 migration guide for help upgrading to the latest version of urllib3!

Added

• Added type hints to the urllib3 module (#1897).
• Added ssl_minimum_version and ssl_maximum_version options which set
  SSLContext.minimum_version and SSLContext.maximum_version (#2110).
• Added support for Zstandard (RFC 8878) when zstandard 1.18.0 or later is installed.
  Added the zstd extra which installs the zstandard package (#1992).
• Added urllib3.response.BaseHTTPResponse class. All future response classes will be subclasses of BaseHTTPResponse (#2083).
• Added top-level urllib3.request function which uses a preconfigured module-global PoolManager instance (#2150).
• Added FullPoolError which is raised when PoolManager(block=True) and a connection is returned to a full pool (#2197).
• Added HTTPHeaderDict to the top-level urllib3 namespace (#2216).
• Added the json parameter to urllib3.request(), PoolManager.request(), and ConnectionPool.request() methods to send JSON bodies in requests. Using this parameter will set the header Content-Type: application/json if Content-Type isn't already defined.
  Added support for parsing JSON response bodies with HTTPResponse.json() method (#2243).
• Added support for configuring header merging behavior with HTTPHeaderDict
  When using a HTTPHeaderDict to provide headers for a request, by default duplicate
  header values will be repeated. But if combine=True is passed into a call to
  HTTPHeaderDict.add, then the added header value will be merged in with an existing
  value into a comma-separated list (X-My-Header: foo, bar) (#2242).
• Added NameResolutionError exception when a DNS error occurs (#2305).
• Added proxy_assert_hostname and proxy_assert_fingerprint kwargs to ProxyManager (#2409).
• Added a configurable backoff_max parameter to the Retry class.
  If a custom backoff_max is provided to the Retry class, it
  will replace the Retry.DEFAULT_BACKOFF_MAX (#2494).
• Added the authority property to the Url class as per RFC 3986 3.2. This property should be used in place of netloc for users who want to include the userinfo (auth) component of the URI (#2520).
• Added the scheme parameter to HTTPConnection.set_tunnel to configure the scheme of the origin being tunnelled to (#1985).
• Added the is_closed, is_connected and has_connected_to_proxy properties to HTTPConnection (#1985).

Removed

• Removed support for Python 2.7, 3.5, and 3.6 (#883, #2336).
• Removed fallback on certificate commonName in match_hostname() function.
  This behavior was deprecated in May 2000 in RFC 2818. Instead only subjectAltName
  is used to verify the hostname by default. To enable verifying the hostname against
  commonName use SSLContext.hostname_checks_common_name = True (#2113).
• Removed support for Python with an ssl module compiled with LibreSSL, CiscoSSL,
  wolfSSL, and all other OpenSSL alternatives. Python is moving to require OpenSSL with PEP 644 (#2168).
• Removed support for OpenSSL versions earlier than 1.1.1 or that don't have SNI support.
  When an incompatible OpenSSL version is detected an ImportError is raised (#2168).
• Removed the list of default ciphers for OpenSSL 1.1.1+ and SecureTransport as their own defaults are already secure (#2082).
• Removed urllib3.contrib.appengine.AppEngineManager and support for Google App Engine Standard Environment (#2044).
• Removed deprecated Retry options method_whitelist, DEFAULT_REDIRECT_HEADERS_BLACKLIST (#2086).
• Removed urllib3.HTTPResponse.from_httplib (#2648).
• Removed default value of None for the request_context parameter of urllib3.PoolManager.connection_from_pool_key. This change should have no effect on users as the default value of None was an invalid option and was never used (#1897).
• Removed the urllib3.request module. urllib3.request.RequestMethods has been made a private API.
  This change was made to ensure that from urllib3 import request imported the top-level request()
  function instead of the urllib3.request module (#2269).
• Removed support for SSLv3.0 from the urllib3.contrib.pyopenssl even when support is available from the compiled OpenSSL library (#2233).
• Removed the deprecated urllib3.contrib.ntlmpool module (#2339).
• Removed DEFAULT_CIPHERS, HAS_SNI, USE_DEFAULT_SSLCONTEXT_CIPHERS, from the private module urllib3.util.ssl_ (#2168).
• Removed urllib3.exceptions.SNIMissingWarning (#2168).
• Removed the _prepare_conn method from HTTPConnectionPool. Previously this was only used to call HTTPSConnection.set_cert() by HTTPSConnectionPool (#1985).
• Removed tls_in_tls_required property from HTTPSConnection. This is now determined from the scheme parameter in HTTPConnection.set_tunnel() (#1985).

Changed

• Changed urllib3.response.HTTPResponse.read to respect the semantics of io.BufferedIOBase regardless of compression. Specifically, this method:
  • Only returns an empty bytes object to indicate EOF (that is, the response has been fully consumed).
  • Never returns more bytes than requested.
  • Can issue any number of system calls: zero, one or multiple.
    If you want each urllib3.response.HTTPResponse.read call to issue a single system call, you need to disable decompression by setting decode_content=False (#2128).
• Changed ssl_version to instead set the corresponding SSLContext.minimum_version
  and SSLContext.maximum_version values. Regardless of ssl_version passed
  SSLContext objects are now constructed using ssl.PROTOCOL_TLS_CLIENT (#2110).
• Changed default SSLContext.minimum_version to be TLSVersion.TLSv1_2 in line with Python 3.10 (#2373).
• Changed ProxyError to wrap any connection error (timeout, TLS, DNS) that occurs when connecting to the proxy (#2482).
• Changed urllib3.util.create_urllib3_context to not override the system cipher suites with
  a default value. The new default will be cipher suites configured by the operating system (#2168).
• Changed multipart/form-data header parameter formatting matches the WHATWG HTML Standard as of 2021-06-10. Control characters in filenames are no longer percent encoded (#2257).
• Changed urllib3.HTTPConnection.getresponse to return an instance of urllib3.HTTPResponse instead of http.client.HTTPResponse (#2648).
• Changed return type of HTTPResponse.getheaders() method to return a list of key-value tuples to match CPython (#1543).
• Changed the error raised when connecting via HTTPS when the ssl module isn't available from SSLError to ImportError (#2589).
• Changed HTTPConnection.request() to always use lowercase chunk boundaries when sending requests with Transfer-Encoding: chunked (#2515).
• Changed enforce_content_length default to True, preventing silent data loss when reading streamed responses (#2514).
• Changed internal implementation of HTTPHeaderDict to use dict instead of collections.OrderedDict for better performance (#2080).
• Changed the urllib3.contrib.pyopenssl module to wrap OpenSSL.SSL.Error with ssl.SSLError in PyOpenSSLContext.load_cert_chain (#2628).
• Changed usage of the deprecated socket.error to OSError (#2120).
• Changed all parameters in the HTTPConnection and HTTPSConnection constructors to be keyword-only except host and port (#1985).
• Changed urllib3.util.is_connection_dropped() to use HTTPConnection.is_connected (#1985).
• Changed HTTPConnection.getresponse() to set the socket timeout from HTTPConnection.timeout value before reading
  data from the socket. This previously was done manually by the HTTPConnectionPool calling HTTPConnection.sock.settimeout(...) (#1985).
• Changed the _proxy_host property to _tunnel_host in HTTPConnectionPool to more closely match how the property is used (value in HTTPConnection.set_tunnel()) (#1985).
• Changed name of Retry.BACK0FF_MAX to be Retry.DEFAULT_BACKOFF_MAX.
• Changed TLS handshakes to use SSLContext.check_hostname when possible (#2452).
• Changed server_hostname to behave like other parameters only used by HTTPSConnectionPool (#2537).
• Changed the default blocksize to 16KB to match OpenSSL's default read amounts (#2348).

Deprecated

• Deprecated urllib3.contrib.pyopenssl module which will be removed in urllib3 v2.1.0 (#2691).
• Deprecated urllib3.contrib.securetransport module which will be removed in urllib3 v2.1.0 (#2692).
• Deprecated ssl_version option in favor of ssl_minimum_version. ssl_version will be removed in urllib3 v2.1.0 (#2110).
• Deprecated the strict parameter as it's not longer needed in Python 3.x. It will be removed in urllib3 v2.1.0 (#2267)
• Deprecated the NewConnectionError.pool attribute which will be removed in urllib3 v2.1.0 (#2271).
• Deprecated format_header_param_html5 and format_header_param in favor of format_multipart_header_param (#2257).
• Deprecated RequestField.header_formatter parameter which will be removed in urllib3 v2.1.0 (#2257).
• Deprecated HTTPSConnection.set_cert() method. Instead pass parameters to the HTTPSConnection constructor (#1985).
• Deprecated HTTPConnection.request_chunked() method which will be removed in urllib3 v2.1.0. Instead pass chunked=True to HTTPConnection.request() (#1985).

Fixed

• Fixed thread-safety issue where accessing a PoolManager with many distinct origins would cause connection pools to be closed while requests are in progress (#1252).
• Fixed an issue where an HTTPConnection instance would erroneously reuse the socket read timeout value from reading the previous response instead of a newly configured connect timeout.
  Instead now if HTTPConnection.timeout is updated before sending the next request the new timeout value will be used (#2645).
• Fixed socket.error.errno when raised from pyOpenSSL's OpenSSL.SSL.SysCallError (#2118).
• Fixed the default value of HTTPSConnection.socket_options to match HTTPConnection (#2213).
• Fixed a bug where headers would be modified by the remove_headers_on_redirect feature (#2272).
• Fixed a reference cycle bug in urllib3.util.connection.create_connection() (#2277).
• Fixed a socket leak if HTTPConnection.connect() fails (#2571).