Install & Compatibility
Where this runs
tested against v0.26.3 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.858s · 23.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.7s · import 0.724s · 25MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
responses
✓ import responses
activate
✓ from responses import activate
Commonly used as a decorator: `@responses.activate`
matchers
✓ from responses import matchers
Used for advanced request body or header matching.
The quickstart demonstrates mocking a GET request using the `@responses.activate` decorator and `responses.add()` method. It sets up a mock response with a JSON body and then makes a `requests.get()` call, which is intercepted by `responses`. Finally, it asserts the response content and verifies that the mock was called.
import requests
import responses
@responses.activate
def test_example_request():
responses.add(
responses.GET,
'http://example.com/api/test',
json={'message': 'Hello, World!'},
status=200,
content_type='application/json'
)
# This request will be intercepted by 'responses'
resp = requests.get('http://example.com/api/test')
assert resp.status_code == 200
assert resp.json() == {'message': 'Hello, World!'}
# Verify that exactly one request was made to the registered URL
assert len(responses.calls) == 1
assert responses.calls[0].request.url == 'http://example.com/api/test'
print("Running test_example_request...")
test_example_request()
print("Test completed successfully.")
Debug
Known issues
breakingIn version 0.26.0, the behavior of `assert_all_requests_are_fired=True` (the default when using `responses.activate` as a context manager or decorator) changed. Assertions about unfired requests are now raised even if an exception occurs within the context manager or decorated function. Previously, these assertions were suppressed, which could hide uncalled mocks.fixReview tests that might rely on exceptions suppressing `responses` assertions. Adjust tests to explicitly handle the assertion failure, or set `assert_all_requests_are_fired=False` if this validation is not needed.
affects: 0.26.0 and later
deprecatedDirect access to `assert_all_requests_are_fired`, `passthru_prefixes`, and `target` from the top-level `responses` module (e.g., `responses.assert_all_requests_are_fired`) is deprecated.fixUse the attributes via `responses.mock`, such as `responses.mock.assert_all_requests_are_fired`, `responses.mock.passthru_prefixes`, and `responses.mock.target` instead.
affects: 0.20.0 and later
deprecatedThe `match_querystring` argument in `Response` and `CallbackResponse` is deprecated.fixFor matching query parameters, use `responses.matchers.query_param_matcher` for dictionary-based matching or `responses.matchers.query_string_matcher` for matching the raw query string.
affects: Pre-0.17.0, still present but discouraged
gotchaBy default, `responses.add` assumes a mock should be consumed once. If `assert_all_requests_are_fired=True` (the default) is active, calling the same URL multiple times with a single `responses.add` definition will cause an `AssertionError` after the first call.fixFor URLs expected to be called multiple times, set `repeat=True` in `responses.add()` (e.g., `responses.add(..., repeat=True)`), or add multiple `responses.add()` calls for each expected interaction.
affects: All versions with `assert_all_requests_are_fired` enabled
gotchaPrior to version 0.25.0, `matchers.header_matcher` did not correctly fail if a header specified in the matcher was entirely missing from the request; it only validated the value of present headers.fixUpgrade to `responses` 0.25.0 or later to ensure `matchers.header_matcher` properly validates the presence of matched headers.
affects: Prior to 0.25.0
gotchaWhen using `responses` alongside other network mocking libraries (e.g., `httpretty`, `moto`) or attempting to make actual network calls within the same test context, conflicts can arise as `responses` extensively patches the `requests` library.fixEnsure `responses.activate`'s scope is properly managed and isolated to avoid interference. If possible, avoid combining multiple patching libraries for the same underlying network functionality in a single test, or use `responses.mock.passthru_all` or `responses.add_passthru` to allow specific real requests.
affects: All versions
Upgrade
Version history
0.26.3latest on PyPI · released Aug 26, 2026
Audit
Dependencies
requestsrequiredThis library mocks 'requests', so 'requests' is a required peer dependency for functionality.