treq

library25.5.0pypypi✓ verified 86d ago

Treq is a high-level HTTP client library for Python, inspired by the popular `requests` library but built upon Twisted's asynchronous networking framework. It simplifies making HTTP requests within Twisted applications by providing a familiar, easy-to-use API for various HTTP methods, JSON handling, and cookie management. The library is actively maintained, currently at version 25.5.0, with a regular release cadence to support new Python and Twisted versions.

http-networking

pip install treq

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · TREQ

treq

http-networkingpythonv25.5.0

Install

6.0s avg

Import

1448ms

Disk

78MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v25.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 1.487s · 75.3MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 6.0s · import 1.409s · 76MB

78MB installed

● package 78MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

get

✓ import treq # ... await treq.get(...)

post

✓ import treq # ... await treq.post(...)

react

✓ from twisted.internet.task import react

✗ from twisted.internet import reactor; reactor.run()

`task.react` is the recommended way to run Twisted applications, handling reactor startup and shutdown automatically.

HTTPClient

✓ from treq.client import HTTPClient

Used for advanced customization of the underlying Twisted Agent.

This example demonstrates how to perform a basic GET request using `treq` and print the response status, headers, and body. It uses `twisted.internet.task.react` to manage the Twisted reactor, ensuring the asynchronous operation runs correctly and the application exits gracefully.

from twisted.internet.task import react import treq import os async def fetch_and_print(reactor): # Using httpbin.org for a simple test endpoint response = await treq.get("https://httpbin.org/get", reactor=reactor) print(f"Status: {response.code} {response.phrase.decode()}") print("Headers:") for k, v in response.headers.getAllRawHeaders(): print(f" {k.decode()}: {', '.join(map(bytes.decode, v))}") body = await response.text() print("Body:") print(body) if __name__ == '__main__': react(fetch_and_print)

Debug

Known issues

breakingMixing the `json` argument with `files` or `data` in a single request is no longer allowed and will raise a `TypeError`.

fix

Use either `json` for JSON payloads or `files`/`data` for form-encoded or multipart data, but not both simultaneously.

affects: >=24.9.0

deprecatedSupport for Python 3.6 was dropped in treq 22.2.0. Support for Python 3.7 and PyPy 3.7/3.8 was deprecated and subsequently removed in later releases (e.g., 23.11.0, 25.5.0). The minimum supported Twisted version has also been incremented over time, currently requiring >=22.10.0 for treq 25.5.0.

fix

Upgrade to Python 3.8+ and ensure your Twisted installation is up-to-date (22.10.0 or newer for treq 25.5.0). Consult the treq changelog for specific version compatibility.

affects: >=22.2.0

gotchaA security vulnerability (CVE-2022-23607) in versions prior to 22.1.0 caused cookies provided as a dictionary to be sent to *all* domains on redirect, potentially exposing sensitive information.

fix

Upgrade to treq 22.1.0 or newer to ensure correct cookie handling and prevent unintended information disclosure.

affects: <22.1.0

gotchaPrior to version 20.4.0, the `params` argument had issues with URL-encoding characters like `&` or `#`, and non-ASCII URLs/parameters could lead to `UnicodeEncodeError`.

fix

Upgrade to treq 20.4.0 or newer. Ensure all string inputs are properly encoded if dealing with older versions, or explicitly use `hyperlink` objects for robust URL construction.

affects: <20.4.0

Errors

Common errors & fixes

TypeError: mixing 'json' with 'files' or 'data' is not allowed

Attempting to send both a JSON payload and form data (or files) in a single HTTP request, which is a breaking change introduced in treq 24.9.0.

fix

Choose only one method for sending the request body: either `json={...}` for a JSON payload, or `data={...}` for form-encoded data, or `files={...}` for multipart file uploads. Do not combine them.

twisted.internet.error.HostnameResolutionError: DNS lookup failed

The Twisted reactor (event loop) was not started or stopped prematurely, preventing network operations from completing.

fix

Ensure your application runs within the Twisted reactor. Use `twisted.internet.task.react(your_main_function)` to properly start and stop the reactor for your asynchronous code.

UnicodeEncodeError: 'ascii' codec can't encode character...

Sending non-ASCII characters in URLs or query parameters with older versions of treq (prior to 20.4.0) that had encoding issues.

fix

Upgrade treq to version 20.4.0 or newer. If stuck on an older version, manually encode URL components using `urllib.parse.quote` or `hyperlink` before passing them to treq.

AttributeError: 'bytes' object has no attribute 'decode'

Attempting to call `.decode()` on a response body that might already be a string (e.g., from `response.text()` or `response.json()`), or forgetting to await `response.text()`/`response.json()` and operating on a Deferred.

fix

Ensure you are awaiting the content retrieval methods (e.g., `body = await response.text()`) and only `decode()` raw `bytes` objects obtained from `await response.content()`.

Upgrade

Version history

25.5.0latest on PyPI · released Jun 3, 2025

Audit

Dependencies

TwistedrequiredTreq is built on top of Twisted's asynchronous event loop and networking components (Agents).

hyperlinkrequiredUsed for URL representation and manipulation within treq's API.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/twisted/treq ↗

packagehttps://pypi.org/project/treq/ ↗

docshttps://treq.readthedocs.io/ ↗

changeloghttps://github.com/twisted/treq/blob/HEAD/CHANGELOG.rst ↗