# treq: High-level Twisted HTTP Client API

Release v26.7.0 (What’s new?).

treq depends on a recent Twisted and a supported version of CPython or PyPy.

## Why?

requests is a wonderful library. I want the same ease of use when writing Twisted applications. treq is not of course a perfect clone of requests. I have tried to stay true to the do-what-I-mean spirit of the requests API and also kept the API familiar to users of Twisted and `twisted.web.client.Agent` on which treq is based.

## Quick Start

Installation

    $ pip install treq

### GET

    async def basic_get(reactor):
        resp = await treq.get("https://httpbin.org/get")
        print(resp.code, resp.phrase)
        print(resp.headers)
        print(await resp.text())

Full example: `basic_get.py`

### POST

    def basic_post(reactor):
        resp = await treq.post(
            "https://httpbin.org/post",
            data={"form": "data"},
        )
        await print_response(resp)

Full example: `basic_post.py`

## Why not 100% requests-alike?

Initially when I started off working on treq I thought the API should look exactly like requests except anything that would involve the network would return a `Deferred`.

Over time while attempting to mimic the requests API it became clear that not enough code could be shared between requests and treq for it to be worth the effort to translate many of the usage patterns from requests.

With the current version of treq I have tried to keep the API simple, yet remain familiar to users of Twisted and its lower-level HTTP libraries.

## Feature Parity with Requests

Even though mimicking the requests API is not a goal, supporting most of its features is. Here is a list of requests features and their status in treq.

| requests | treq
International Domains and URLs | yes | yes
Keep-Alive & Connection Pooling | yes | yes
Sessions with Cookie Persistence | yes | yes
Browser-style SSL Verification | yes | yes
Basic Authentication | yes | yes
Digest Authentication | yes | no
Automatic Decompression | yes | yes
Unicode Response Bodies | yes | yes
Multipart File Uploads | yes | yes
Connection Timeouts | yes | yes
HTTP(S) Proxy Support | yes | no
.netrc support | yes | no

## Table of Contents

- Use Cases
  - Handling Streaming Responses
  - URLs, URIs, and Hyperlinks
  - Query Parameters
  - JSON
  - Auth
  - Redirects
  - Cookies
  - Customizing the Twisted Agent
- Testing Helpers
  - Writing tests for HTTP clients
    - Loosely matching the request
  - Writing tests for Twisted Web resources
- API Reference
  - Making Requests
    - `request()`
    - `get()`
    - `head()`
    - `post()`
    - `put()`
    - `patch()`
    - `delete()`
  - Accessing Content
    - `collect()`
    - `content()`
    - `text_content()`
    - `json_content()`
- The HTTP Client
  - `HTTPClient`
    - `HTTPClient.request()`
    - `HTTPClient.get()`
    - `HTTPClient.head()`
    - `HTTPClient.post()`
    - `HTTPClient.put()`
    - `HTTPClient.patch()`
    - `HTTPClient.delete()`
  - Augmented Response Objects
    - `_Response`
  - Authentication
    - `add_auth()`
    - `add_basic_auth()`
    - `UnknownAuthConfig`
  - Cookies
    - `scoped_cookie()`
    - `search()`
    - `IndexableCookieJar`
    - `CookieCollision`
  - Test Helpers
    - StubTreq Objects
    - RequestTraversalAgent Objects
    - RequestSequence Objects
    - StringStubbingResource Objects
    - HasHeaders Objects
  - MultiPartProducer Objects
    - `MultiPartProducer`
- Changelog
  - 26.7.0 (2026-07-01)
    - Features
    - Bugfixes
    - Deprecations and Removals
  - 25.5.0 (2025-05-31)
    - Features
    - Improved Documentation
    - Deprecations and Removals
  - 24.9.1 (2024-09-19)
    - Bugfixes
  - 24.9.0 (2024-09-17)
    - Features
    - Bugfixes
    - Deprecations and Removals
    - Misc
  - 23.11.0 (2023-11-03)
    - Features
    - Deprecations and Removals
    - Misc
  - 22.2.0 (2022-02-08)
    - Features
    - Bugfixes
    - Deprecations and Removals
  - 22.1.0 (2022-01-29)
    - Bugfixes
  - 21.5.0 (2021-05-24)
    - Features
    - Bugfixes
    - Improved Documentation
    - Deprecations and Removals
  - 21.1.0 (2021-01-14)
    - Features
    - Bugfixes
    - Improved Documentation
    - Deprecations and Removals
  - 20.9.0 (2020-09-27)
    - Features
    - Improved Documentation
  - 20.4.1 (2020-04-16)
    - Bugfixes
  - 20.4.0 (2020-04-16)
    - Features
    - Bugfixes
    - Improved Documentation
  - 20.3.0 (2020-03-15)
    - Features
    - Bugfixes
    - Improved Documentation
    - Deprecations and Removals
    - Misc

# Indices and tables

- Index

- Module Index

- Search Page