CINXE.COM

<!DOCTYPE html> <html lang="en" data-content_root="./"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" /> <title>Requests: HTTP for Humans™ — Requests 2.32.3 documentation</title> <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=6625fa76" /> <link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=1fe5e9f7" /> <script src="_static/documentation_options.js?v=5fb65c81"></script> <script src="_static/doctools.js?v=888ff710"></script> <script src="_static/sphinx_highlight.js?v=dc90522c"></script> <link rel="index" title="Index" href="genindex/" /> <link rel="search" title="Search" href="search/" /> <link rel="next" title="Installation of Requests" href="user/install/" /> <link rel="stylesheet" href="_static/custom.css" type="text/css" /> <script async type="text/javascript" src="/_/static/javascript/readthedocs-addons.js"></script><meta name="readthedocs-project-slug" content="requests" /><meta name="readthedocs-version-slug" content="latest" /><meta name="readthedocs-resolver-filename" content="/" /><meta name="readthedocs-http-status" content="200" /></head><body> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <section id="requests-http-for-humans"> <h1>Requests: HTTP for Humans™<a class="headerlink" href="#requests-http-for-humans" title="Link to this heading">¶</a></h1> <p>Release v2.32.3. (<a class="reference internal" href="user/install/#install"><span class="std std-ref">Installation</span></a>)</p> <a class="reference external image-reference" href="https://pepy.tech/project/requests"><img alt="Requests Downloads Per Month Badge" src="https://static.pepy.tech/badge/requests/month" /></a> <a class="reference external image-reference" href="https://pypi.org/project/requests/"><img alt="License Badge" src="https://img.shields.io/pypi/l/requests.svg" /></a> <a class="reference external image-reference" href="https://pypi.org/project/requests/"><img alt="Wheel Support Badge" src="https://img.shields.io/pypi/wheel/requests.svg" /></a> <a class="reference external image-reference" href="https://pypi.org/project/requests/"><img alt="Python Version Support Badge" src="https://img.shields.io/pypi/pyversions/requests.svg" /></a> <p><strong>Requests</strong> is an elegant and simple HTTP library for Python, built for human beings.</p> <hr class="docutils" /> <p><strong>Behold, the power of Requests</strong>:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'https://api.github.com/user'</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="p">(</span><span class="s1">'user'</span><span class="p">,</span> <span class="s1">'pass'</span><span class="p">))</span> <span class="gp">>>> </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="go">200</span> <span class="gp">>>> </span><span class="n">r</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s1">'content-type'</span><span class="p">]</span> <span class="go">'application/json; charset=utf8'</span> <span class="gp">>>> </span><span class="n">r</span><span class="o">.</span><span class="n">encoding</span> <span class="go">'utf-8'</span> <span class="gp">>>> </span><span class="n">r</span><span class="o">.</span><span class="n">text</span> <span class="go">'{"type":"User"...'</span> <span class="gp">>>> </span><span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()</span> <span class="go">{'private_gists': 419, 'total_private_repos': 77, ...}</span> </pre></div> </div> <p>See <a class="reference external" href="https://gist.github.com/973705">similar code, sans Requests</a>.</p> <p><strong>Requests</strong> allows you to send HTTP/1.1 requests extremely easily. There’s no need to manually add query strings to your URLs, or to form-encode your POST data. Keep-alive and HTTP connection pooling are 100% automatic, thanks to <a class="reference external" href="https://github.com/urllib3/urllib3">urllib3</a>.</p> <section id="beloved-features"> <h2>Beloved Features<a class="headerlink" href="#beloved-features" title="Link to this heading">¶</a></h2> <p>Requests is ready for today’s web.</p> <ul class="simple"> <li><p>Keep-Alive & Connection Pooling</p></li> <li><p>International Domains and URLs</p></li> <li><p>Sessions with Cookie Persistence</p></li> <li><p>Browser-style SSL Verification</p></li> <li><p>Automatic Content Decoding</p></li> <li><p>Basic/Digest Authentication</p></li> <li><p>Elegant Key/Value Cookies</p></li> <li><p>Automatic Decompression</p></li> <li><p>Unicode Response Bodies</p></li> <li><p>HTTP(S) Proxy Support</p></li> <li><p>Multipart File Uploads</p></li> <li><p>Streaming Downloads</p></li> <li><p>Connection Timeouts</p></li> <li><p>Chunked Requests</p></li> <li><p><code class="docutils literal notranslate"><span class="pre">.netrc</span></code> Support</p></li> </ul> <p>Requests officially supports Python 3.8+, and runs great on PyPy.</p> </section> <section id="the-user-guide"> <h2>The User Guide<a class="headerlink" href="#the-user-guide" title="Link to this heading">¶</a></h2> <p>This part of the documentation, which is mostly prose, begins with some background information about Requests, then focuses on step-by-step instructions for getting the most out of Requests.</p> <div class="toctree-wrapper compound"> <ul> <li class="toctree-l1"><a class="reference internal" href="user/install/">Installation of Requests</a><ul> <li class="toctree-l2"><a class="reference internal" href="user/install/#python-m-pip-install-requests">$ python -m pip install requests</a></li> <li class="toctree-l2"><a class="reference internal" href="user/install/#get-the-source-code">Get the Source Code</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="user/quickstart/">Quickstart</a><ul> <li class="toctree-l2"><a class="reference internal" href="user/quickstart/#make-a-request">Make a Request</a></li> <li class="toctree-l2"><a class="reference internal" href="user/quickstart/#passing-parameters-in-urls">Passing Parameters In URLs</a></li> <li class="toctree-l2"><a class="reference internal" href="user/quickstart/#response-content">Response Content</a></li> <li class="toctree-l2"><a class="reference internal" href="user/quickstart/#binary-response-content">Binary Response Content</a></li> <li class="toctree-l2"><a class="reference internal" href="user/quickstart/#json-response-content">JSON Response Content</a></li> <li class="toctree-l2"><a class="reference internal" href="user/quickstart/#raw-response-content">Raw Response Content</a></li> <li class="toctree-l2"><a class="reference internal" href="user/quickstart/#custom-headers">Custom Headers</a></li> <li class="toctree-l2"><a class="reference internal" href="user/quickstart/#more-complicated-post-requests">More complicated POST requests</a></li> <li class="toctree-l2"><a class="reference internal" href="user/quickstart/#post-a-multipart-encoded-file">POST a Multipart-Encoded File</a></li> <li class="toctree-l2"><a class="reference internal" href="user/quickstart/#response-status-codes">Response Status Codes</a></li> <li class="toctree-l2"><a class="reference internal" href="user/quickstart/#response-headers">Response Headers</a></li> <li class="toctree-l2"><a class="reference internal" href="user/quickstart/#cookies">Cookies</a></li> <li class="toctree-l2"><a class="reference internal" href="user/quickstart/#redirection-and-history">Redirection and History</a></li> <li class="toctree-l2"><a class="reference internal" href="user/quickstart/#timeouts">Timeouts</a></li> <li class="toctree-l2"><a class="reference internal" href="user/quickstart/#errors-and-exceptions">Errors and Exceptions</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="user/advanced/">Advanced Usage</a><ul> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#session-objects">Session Objects</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#request-and-response-objects">Request and Response Objects</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#prepared-requests">Prepared Requests</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#ssl-cert-verification">SSL Cert Verification</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#client-side-certificates">Client Side Certificates</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#ca-certificates">CA Certificates</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#body-content-workflow">Body Content Workflow</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#keep-alive">Keep-Alive</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#streaming-uploads">Streaming Uploads</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#chunk-encoded-requests">Chunk-Encoded Requests</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#post-multiple-multipart-encoded-files">POST Multiple Multipart-Encoded Files</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#event-hooks">Event Hooks</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#custom-authentication">Custom Authentication</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#streaming-requests">Streaming Requests</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#proxies">Proxies</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#compliance">Compliance</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#http-verbs">HTTP Verbs</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#custom-verbs">Custom Verbs</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#link-headers">Link Headers</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#transport-adapters">Transport Adapters</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#blocking-or-non-blocking">Blocking Or Non-Blocking?</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#header-ordering">Header Ordering</a></li> <li class="toctree-l2"><a class="reference internal" href="user/advanced/#timeouts">Timeouts</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="user/authentication/">Authentication</a><ul> <li class="toctree-l2"><a class="reference internal" href="user/authentication/#basic-authentication">Basic Authentication</a></li> <li class="toctree-l2"><a class="reference internal" href="user/authentication/#digest-authentication">Digest Authentication</a></li> <li class="toctree-l2"><a class="reference internal" href="user/authentication/#oauth-1-authentication">OAuth 1 Authentication</a></li> <li class="toctree-l2"><a class="reference internal" href="user/authentication/#oauth-2-and-openid-connect-authentication">OAuth 2 and OpenID Connect Authentication</a></li> <li class="toctree-l2"><a class="reference internal" href="user/authentication/#other-authentication">Other Authentication</a></li> <li class="toctree-l2"><a class="reference internal" href="user/authentication/#new-forms-of-authentication">New Forms of Authentication</a></li> </ul> </li> </ul> </div> </section> <section id="the-community-guide"> <h2>The Community Guide<a class="headerlink" href="#the-community-guide" title="Link to this heading">¶</a></h2> <p>This part of the documentation, which is mostly prose, details the Requests ecosystem and community.</p> <div class="toctree-wrapper compound"> <ul> <li class="toctree-l1"><a class="reference internal" href="community/recommended/">Recommended Packages and Extensions</a><ul> <li class="toctree-l2"><a class="reference internal" href="community/recommended/#certifi-ca-bundle">Certifi CA Bundle</a></li> <li class="toctree-l2"><a class="reference internal" href="community/recommended/#cachecontrol">CacheControl</a></li> <li class="toctree-l2"><a class="reference internal" href="community/recommended/#requests-toolbelt">Requests-Toolbelt</a></li> <li class="toctree-l2"><a class="reference internal" href="community/recommended/#requests-threads">Requests-Threads</a></li> <li class="toctree-l2"><a class="reference internal" href="community/recommended/#requests-oauthlib">Requests-OAuthlib</a></li> <li class="toctree-l2"><a class="reference internal" href="community/recommended/#betamax">Betamax</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="community/faq/">Frequently Asked Questions</a><ul> <li class="toctree-l2"><a class="reference internal" href="community/faq/#encoded-data">Encoded Data?</a></li> <li class="toctree-l2"><a class="reference internal" href="community/faq/#custom-user-agents">Custom User-Agents?</a></li> <li class="toctree-l2"><a class="reference internal" href="community/faq/#why-not-httplib2">Why not Httplib2?</a></li> <li class="toctree-l2"><a class="reference internal" href="community/faq/#python-3-support">Python 3 Support?</a></li> <li class="toctree-l2"><a class="reference internal" href="community/faq/#python-2-support">Python 2 Support?</a></li> <li class="toctree-l2"><a class="reference internal" href="community/faq/#what-are-hostname-doesn-t-match-errors">What are “hostname doesn’t match” errors?</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="community/out-there/">Integrations</a></li> <li class="toctree-l1"><a class="reference internal" href="community/out-there/#articles-talks">Articles & Talks</a></li> <li class="toctree-l1"><a class="reference internal" href="community/support/">Support</a><ul> <li class="toctree-l2"><a class="reference internal" href="community/support/#stack-overflow">Stack Overflow</a></li> <li class="toctree-l2"><a class="reference internal" href="community/support/#file-an-issue">File an Issue</a></li> <li class="toctree-l2"><a class="reference internal" href="community/support/#send-a-tweet">Send a Tweet</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="community/vulnerabilities/">Vulnerability Disclosure</a></li> <li class="toctree-l1"><a class="reference internal" href="community/release-process/">Release Process and Rules</a><ul> <li class="toctree-l2"><a class="reference internal" href="community/release-process/#major-releases">Major Releases</a></li> <li class="toctree-l2"><a class="reference internal" href="community/release-process/#minor-releases">Minor Releases</a></li> <li class="toctree-l2"><a class="reference internal" href="community/release-process/#hotfix-releases">Hotfix Releases</a></li> <li class="toctree-l2"><a class="reference internal" href="community/release-process/#reasoning">Reasoning</a></li> </ul> </li> </ul> </div> <div class="toctree-wrapper compound"> <ul> <li class="toctree-l1"><a class="reference internal" href="community/updates/">Community Updates</a></li> <li class="toctree-l1"><a class="reference internal" href="community/updates/#release-history">Release History</a></li> </ul> </div> </section> <section id="the-api-documentation-guide"> <h2>The API Documentation / Guide<a class="headerlink" href="#the-api-documentation-guide" title="Link to this heading">¶</a></h2> <p>If you are looking for information on a specific function, class, or method, this part of the documentation is for you.</p> <div class="toctree-wrapper compound"> <ul> <li class="toctree-l1"><a class="reference internal" href="api/">Developer Interface</a><ul> <li class="toctree-l2"><a class="reference internal" href="api/#main-interface">Main Interface</a></li> <li class="toctree-l2"><a class="reference internal" href="api/#exceptions">Exceptions</a></li> <li class="toctree-l2"><a class="reference internal" href="api/#request-sessions">Request Sessions</a></li> <li class="toctree-l2"><a class="reference internal" href="api/#lower-level-classes">Lower-Level Classes</a></li> <li class="toctree-l2"><a class="reference internal" href="api/#lower-lower-level-classes">Lower-Lower-Level Classes</a></li> <li class="toctree-l2"><a class="reference internal" href="api/#authentication">Authentication</a></li> <li class="toctree-l2"><a class="reference internal" href="api/#encodings">Encodings</a></li> <li class="toctree-l2"><a class="reference internal" href="api/#cookies">Cookies</a></li> <li class="toctree-l2"><a class="reference internal" href="api/#status-code-lookup">Status Code Lookup</a></li> <li class="toctree-l2"><a class="reference internal" href="api/#migrating-to-1-x">Migrating to 1.x</a></li> <li class="toctree-l2"><a class="reference internal" href="api/#migrating-to-2-x">Migrating to 2.x</a></li> </ul> </li> </ul> </div> </section> <section id="the-contributor-guide"> <h2>The Contributor Guide<a class="headerlink" href="#the-contributor-guide" title="Link to this heading">¶</a></h2> <p>If you want to contribute to the project, this part of the documentation is for you.</p> <div class="toctree-wrapper compound"> <ul> <li class="toctree-l1"><a class="reference internal" href="dev/contributing/">Contributor’s Guide</a><ul> <li class="toctree-l2"><a class="reference internal" href="dev/contributing/#be-cordial">Be Cordial</a></li> <li class="toctree-l2"><a class="reference internal" href="dev/contributing/#get-early-feedback">Get Early Feedback</a></li> <li class="toctree-l2"><a class="reference internal" href="dev/contributing/#contribution-suitability">Contribution Suitability</a></li> <li class="toctree-l2"><a class="reference internal" href="dev/contributing/#code-contributions">Code Contributions</a><ul> <li class="toctree-l3"><a class="reference internal" href="dev/contributing/#steps-for-submitting-code">Steps for Submitting Code</a></li> <li class="toctree-l3"><a class="reference internal" href="dev/contributing/#code-review">Code Review</a></li> <li class="toctree-l3"><a class="reference internal" href="dev/contributing/#code-style">Code Style</a></li> <li class="toctree-l3"><a class="reference internal" href="dev/contributing/#new-contributors">New Contributors</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="dev/contributing/#documentation-contributions">Documentation Contributions</a></li> <li class="toctree-l2"><a class="reference internal" href="dev/contributing/#bug-reports">Bug Reports</a></li> <li class="toctree-l2"><a class="reference internal" href="dev/contributing/#feature-requests">Feature Requests</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="dev/authors/">Authors</a><ul> <li class="toctree-l2"><a class="reference internal" href="dev/authors/#keepers-of-the-crystals">Keepers of the Crystals</a></li> <li class="toctree-l2"><a class="reference internal" href="dev/authors/#previous-keepers-of-crystals">Previous Keepers of Crystals</a></li> <li class="toctree-l2"><a class="reference internal" href="dev/authors/#patches-and-suggestions">Patches and Suggestions</a></li> </ul> </li> </ul> </div> <p>There are no more guides. You are now guideless. Good luck.</p> </section> </section> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebarwrapper"><p class="logo"> <a href="#"> <img class="logo" src="_static/requests-sidebar.png" alt="Requests logo" /> </a> </p> <p> <iframe src="https://ghbtns.com/github-btn.html?user=psf&repo=requests&type=watch&count=true&size=large" allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe> </p> <p> Requests is an elegant and simple HTTP library for Python, built for human beings. </p> <h3>Useful Links</h3> <ul> <li><a href="user/quickstart/">Quickstart</a></li> <li><a href="user/advanced/">Advanced Usage</a></li> <li><a href="api/">API Reference</a></li> <li><a href="community/updates/#release-history">Release History</a></li> <li><a href="dev/contributing/">Contributors Guide</a></li> <p></p> <li><a href="community/recommended/">Recommended Packages and Extensions</a></li> <p></p> <li><a href="https://github.com/psf/requests">Requests @ GitHub</a></li> <li><a href="https://pypi.org/project/requests/">Requests @ PyPI</a></li> <li><a href="https://github.com/psf/requests/issues">Issue Tracker</a></li> </ul> <div id="native-ribbon"> </div> <div id="searchbox" style="display: none" role="search"> <h3 id="searchlabel">Quick search</h3> <div class="searchformwrapper"> <form class="search" action="search/" method="get"> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> <input type="submit" value="Go" /> </form> </div> </div> <script>document.getElementById('searchbox').style.display = "block"</script>  <style type="text/css"> /* Rezzy requires precise alignment. */ img.logo {margin-left: -20px!important;} /* "Quick Search" should be capitalized. */ div#searchbox h3 {text-transform: capitalize;} /* Make the document a little wider, less code is cut-off. */ div.document {width: 1008px;} /* Much-improved spacing around code blocks. */ div.highlight pre {padding: 11px 14px;} /* Remain Responsive! */ @media screen and (max-width: 1008px) { div.sphinxsidebar {display: none;} div.document {width: 100%!important;} /* Have code blocks escape the document right-margin. */ div.highlight pre {margin-right: -30px;} } </style>  <script type="text/javascript" src="//m.servedby-buysellads.com/monetization.js"></script> <div id="native-ribbon"> </div> <script> _bsa.init('custom', 'CK7D62JU', 'placement:pythonrequestsorg', { target: '#native-ribbon', template: ` <div class="native-sponsor">Sponsored by ##company## — Learn More</div> <a href="##link##" class="native-flex"> <style> #native-ribbon #_custom_ { background: linear-gradient(-30deg, ##backgroundColor##E5, ##backgroundColor##E5 45%, ##backgroundColor## 45%) #fff; } .native-details, .native-sponsor, .native-bsa { color: ##textColor## !important; } .native-details:hover { color: ##textColorHover## !important; } .native-cta { color: ##ctaTextColor##; background-color: ##ctaBackgroundColor##; } .native-cta:hover { color: ##ctaTextColorHover##; background-color: ##ctaBackgroundColorHover##; } </style> <div class="native-main"> <img class="native-img" src="##logo##"> <div class="native-details"> <span class="native-company">##title##</span> <span class="native-desc">##description##</span> </div> </div> <span class="native-cta">##callToAction##</span> </a> </div> ` } ); </script> </div> </div> <div class="clearer"></div> </div> <div class="footer"> ©MMXVIX. A <a href="https://kenreitz.org/projects">Kenneth Reitz</a> Project. </div> <a href="https://github.com/requests/requests" class="github"> <img style="position: absolute; top: 0; right: 0; border: 0;" src="https://github.blog/wp-content/uploads/2008/12/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" class="github"/> </a> </body> </html>