NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #818 most downloaded on PyPI
Automatically mock your HTTP interactions to simplify and speed up testing
Latest stable
9.4.2
Last release 20 days ago
02 Nov 2026
Release timing varies
gaps range from 8 days to 11 months
Most releases are documented
notes for 48 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
14 years old
91 releases · first in 2013
Drag across the ruler to compare, or tap a release to open it.
Fix urllib3 pools with block=True, e.g. a requests session with HTTPAdapter(pool_block=True), waiting forever for a free connection in a cassette, or
block=True, e.g. a requests session with HTTPAdapter(pool_block=True), waiting forever for a free connection in a cassette, or when used before, after or across cassettes. A response now returns its connection to the pool once its body has been read, as in urllib3, and vcrpy keeps a pool's free slots when it takes connections out of it as a cassette starts or stops using the pool. A response finished after its cassette has exited gives back only the slot, not the cassette's connection (#949, #1094) - thanks @nk-batman21Full Changelog: https://github.com/kevin1024/vcrpy/compare/v9.4.1...v9.4.2
Don't fail with ImportError: cannot import name 'HTTPHeaderDict' on urllib3 1.x, such as the 1.26 that Debian oldstable ships. The urllib3 stub import
ImportError: cannot import name 'HTTPHeaderDict' on urllib3 1.x, such as the 1.26 that Debian oldstable ships. The urllib3 stub imported HTTPHeaderDict from the top level of urllib3, which only exports it from 2.0 on, so use_cassette() raised while building its patchers and nothing could be recorded (#1092, #1093) - thanks @inchang-ingFull Changelog: https://github.com/kevin1024/vcrpy/compare/v9.4.0...v9.4.1
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Requests made through SOCKS proxies with requests and urllib3 (socks5:// and socks5h://, with PySocks installed) are now recorded and played back. url
Requests made through SOCKS proxies with requests and urllib3 (socks5:// and socks5h://, with PySocks installed) are now recorded and played back. urllib3 uses its own connection classes for them, which vcrpy didn't patch, so these requests skipped the cassette entirely (#547, #548, #1087).
filter_post_data_parameters now filters the fields of multipart/form-data request bodies, e.g. requests.post(url, data={"api_key": ...}, files=...). Before, it treated them as urlencoded forms and didn't find their fields, so their values were recorded (#521, #1090).
If you match on body: requests are filtered before they're matched, so cassettes recorded with unfiltered multipart bodies need re-recording.
CannotOverwriteExistingCassetteException, when a vcr.patch.force_reset() window opened elsewhere is closed late by the garbage collector while the cassette is in use (#979, #1051, #1088) - thanks @yeion7, from #1052AttributeError: 'str' object has no attribute 'get_all' when requests builds a response from a urllib.request response, e.g. with HTTPAdapter.build_response() (#956, #1089)Full Changelog: https://github.com/kevin1024/vcrpy/compare/v9.3.2...v9.4.0
Don't open a real connection for HTTPS requests played back from a cassette in the new_episodes record mode. urllib3 connects before sending a request
new_episodes record mode. urllib3 connects before sending a request, before vcrpy knows whether it will be played back, so every such request made a TLS handshake, and failed without network access (#515, #1086)TypeError when use_cassette() without a path is used as a context manager, instead of KeyError: 'path'. A path can be left out only when decorating a function (#570)filter_post_data_parameters crashing with AttributeError on iterator request bodies, e.g. a generator passed as data. Like file bodies, they're left unfiltered (#814)inject_cassette, which passes the cassette to a decorated function, e.g. to rewind it or make assertions (#207, #493)Full Changelog: https://github.com/kevin1024/vcrpy/compare/v9.3.1...v9.3.2
Log a warning when a cassette file exists but can't be decoded, instead of silently treating it as empty, where recording could overwrite it (#501, #1
Request can be imported from vcr, e.g. vcr.Request("GET", uri, body, headers), as the docs already called it (#759) - thanks @lewisdawsonFull Changelog: https://github.com/kevin1024/vcrpy/compare/v9.3.0...v9.3.1
Cassette metadata (#934, thanks @hasier): store values that aren't part of an interaction, such as a seed for random IDs a test sends, so they're the
Cassette metadata (#934, thanks @hasier): store values that aren't part of an interaction, such as a seed for random IDs a test sends, so they're the same when a cassette is recorded and played back.
with my_vcr.use_cassette("test.yaml") as cass:
seed = cass.get_metadata("seed", random.getrandbits(128))
The cassette stores default the first time and returns the stored value after that. If the record mode doesn't allow changing the cassette, a missing key raises MissingMetadataError, a CannotOverwriteExistingCassetteException. See the docs.
skip_patchers (#944, #1070, thanks @smoltafet): leave some HTTP libraries unpatched. For example, skip_patchers=["httpx"] stops an httpx client with an aiohttp transport (httpx-aiohttp) from being recorded twice.
filter_nested_post_data_parameters (#936, #937, thanks @tighwm and @JargeZ): make filter_post_data_parameters also filter keys in nested objects of JSON request bodies, such as JSON-RPC params. It's opt-in, so existing setups don't filter more than before.
ignore_hosts accepts compiled regular expressions (#779, thanks @silviumarcu), which match whole host names: ignore_hosts=["example.com", re.compile(r".*\.actions\.githubusercontent\.com")].
allow_playback_repeats also applies while recording (#878, #879, thanks @pyoor): a request that matches one already recorded gets the recorded response, instead of being sent and recorded again. When played back, such requests got the first response anyway.
TypeError or JSONDecodeError (#579, #1081, thanks @nk-batman21)ignore_localhost or ignore_hosts, no longer have their response body read by vcrpy, so they stream as usual (#978, thanks @AronsonDan)release_conn() on a streamed response returns its connection to the pool (#1084, thanks @edsonsims)drop_unused_requests no longer saves an interaction once per playback when allow_playback_repeats is setbefore_record_response also runs when a cassette is loaded, so it should be idempotent (#1042, #1044, thanks @ciastek)urllib.request instead of Python 2's urllib2 (#998, thanks @TejasAmle)Full Changelog: https://github.com/kevin1024/vcrpy/compare/v9.2.0...v9.3.0
`python my_vcr = vcr.VCR(filter_sensitive_data={" ": os.environ.get("API_KEY", "fake-api-key")}) `
filter_sensitive_datamy_vcr = vcr.VCR(filter_sensitive_data={"<API_KEY>": os.environ.get("API_KEY", "fake-api-key")})
Every occurrence of the value in a recorded interaction, in the URL, headers and request and response bodies, is replaced with the placeholder when the cassette is saved, and put back when it's loaded. So:
<API_KEY>,Values can also be functions of the interaction. See the docs for using it in CI without the real secret, and for values that are encoded differently in different places. Modeled on Ruby VCR's option of the same name.
before_save_interaction and after_load_interaction get each interaction's request and response, plus the cassette if they take a third argument, when a cassette is saved and loaded. They return them, changed or not, or None to leave the interaction out. Unlike before_record_request and before_record_response, they run exactly once per interaction. Some uses, from issues:
See the docs for examples. They're modeled on Ruby VCR's before_record and before_playback hooks, and filter_sensitive_data is built on them. Thanks to the authors of #679 and #594, which explored this.
Cassettes also have a new read-only path property.
Full Changelog: https://github.com/kevin1024/vcrpy/compare/v9.1.0...v9.2.0
Replayed aiohttp responses now have raw_headers, so code that reads them (e.g. httpx-aiohttp) works on replay (#970, #1034). Thanks @HostX0
raw_headers, so code that reads them (e.g. httpx-aiohttp) works on replay (#970, #1034). Thanks @HostX0release_conn(), for code that releases pooled responses (#816, #1054). Thanks @cristianchiriacpathlib.Path and other path-like objects work for cassette paths and cassette_library_dir (#567, #920, #1064). Thanks @fredrikblaufilter_post_data_parameters matches urlencoded parameter names, so e.g. api:key also filters api%3Akey (#686, #1066). Thanks @b84330808body matcher no longer crashes on form-urlencoded and XML-RPC requests without a body (#913, #1032). Thanks @M001Nignore_localhost also ignores ::1 (#639). Thanks @dragonpaw for the reportjson(), as urllib3 2.x responses do (#774). Thanks @gschnellOnera for the reportuse_cassette accepts a persister option, to use a custom persister for one cassette (#575). Thanks @gioele for the reportFull Changelog: https://github.com/kevin1024/vcrpy/compare/v9.0.0...v9.1.0
9.0.0 has five changes that can affect existing test suites:
9.0.0 has five changes that can affect existing test suites:
CannotOverwriteExistingCassetteException message. If your code or tests match on the message text (e.g. "Can't overwrite existing cassette"), update them. The exception class and its cassette and failed_request attributes are unchanged, and a new reason attribute ("cassette_not_found", "already_played", "no_match" or "nothing_similar") is a sturdier thing to check (#1076).filter_post_data_parameters now filters request bodies for every HTTP method, not just POST (#328, #1004). Requests are filtered before they're matched, so if you match on body, re-record cassettes that have unfiltered PUT/PATCH/DELETE bodies. vcr.filters.replace_post_data_parameters itself still only filters POST; use the new replace_body_parameters for any method.raise_for_status is used (on the session or the request), and replaying them raises like aiohttp does (#635, #925). Before, they weren't recorded, and a replayed error response didn't raise.HTTPHeaderDict headers, as they do without vcrpy, instead of an HTTPMessage (#841, #1015).The CannotOverwriteExistingCassetteException message now says what actually went wrong, shows how the closest recorded requests differ, and suggests how to fix it (#1076). It fixes:
For example:
Can't play back this request: it matches 1 recorded interaction, but that has already been played back.
record_mode 'none' doesn't record new requests.
GET https://example.com/foo
Cassette: tests/cassettes/ex.yaml
record_mode: none
match_on: method, scheme, host, port, path, query
interactions: 1 recorded, 1 played
How to fix:
* If it's fine for this request to get the same response each time, set
allow_playback_repeats=True [1].
* Otherwise record the extra request: run once with record_mode='new_episodes'
[2].
[1] https://vcrpy.readthedocs.io/en/latest/advanced.html#playback-repeats
[2] https://vcrpy.readthedocs.io/en/latest/usage.html#record-modes
Thanks @philsong4-ai (#1027) and @ChrisJr404 (#1037) for the PRs that started this.
raise_for_status is used (#635, #925). Thanks @andrescollaresfilter_post_data_parameters filters request bodies for every HTTP method (#328, #1004). Thanks @andrescollaresLink headers) keep every value in urllib3 and requests responses (#947, #1015). Thanks @Sanjays2402body matcher no longer crashes when a body doesn't parse as its headers say, e.g. invalid JSON sent as application/json (#1075)Full Changelog: https://github.com/kevin1024/vcrpy/compare/v8.5.0...v9.0.0
Streaming a response body from response.content (read(), iter_chunked(), readline() loops, ...) while recording no longer returns an empty body
response.content (read(), iter_chunked(), readline() loops, ...) while recording no longer returns an empty body (#502)readline() loops on replayed responses now reach the end of the body instead of restarting from the start on each access. This fixes the infinite loop when replaying google-genai streaming responses (#927)response.content is now aiohttp's own StreamReader, both when recording and on replay. iter_any() and iter_chunks() work, lines over 64 KiB are no longer refused, and readuntil(), is_eof(), total_bytes and the rest of its API are availableAll three are from #1055 — thanks @pylaterreur!
If your tests patch vcr.stubs.aiohttp_stubs to work around #502 or #927 (for example by overriding MockClientResponse.content, or by putting the recorded body back with unread_data()), remove the patch: it is no longer needed, and no longer works.
filter_post_data_parameters crashing with UnicodeDecodeError on binary request bodies passed as bytes or bytearray, which are now left untouched, and stop it mangling form segments without a = (#660, #1039). Thanks @philsong4-aidata={"file": f}), which crashed with TypeError: cannot pickle '_io.BufferedReader' object. The file's contents are recorded and the whole file is still sent (#737, #1073). Thanks @LilSpazJoekp for the reportFull Changelog: https://github.com/kevin1024/vcrpy/compare/v8.4.0...v8.5.0
Fix re-recording in the all record mode (#1071, fixes #578 and #208):
all record modeall record mode (#1071, fixes #578 and #208):
drop_unused_requests=True, the cassette is now replaced with only what was just recorded. Before, it was saved empty.match_on setting. With loose matchers (e.g. match_on=["method"]), one new request can replace many old ones. Cassettes re-recorded in all mode also no longer accumulate responses across runs.https://example.com not matching cassettes that recorded them as https://example.com/, a regression in 8.2.0 (#1013, #1031). The uri matcher is otherwise as strict as before. Thanks @DSeaStarAttributeError: 'VCRFakeSocket' object has no attribute 'gettimeout' when niquests reuses a pooled connection with urllib3-future 2.25.901 or later (#1056). Thanks @pylaterreurContent-Length instead of chunked encoding, which some servers reject (#1002)Full Changelog: https://github.com/kevin1024/vcrpy/compare/v8.3.0...v8.4.0
Add support for niquests (#980) — thanks @ionelmc
vcr.serializers.yamlserializer.with_custom_tags(...) builds a YAML serializer supporting custom Python object tags on both record and replay, registered per VCR instance via register_serializer (#1007, #1009) — thanks @Polandia94Full Changelog: https://github.com/kevin1024/vcrpy/compare/v8.2.1...v8.3.0
SECURITY: Cassettes are now loaded with a safe YAML loader, preventing arbitrary code execution when a cassette from an untrusted source is loaded. Pr
!!python/object/apply:os.system) would execute code on load, including via the normal vcr.use_cassette() path. Existing cassettes (including file-upload/streaming bodies) continue to load. Advisory: GHSA-rpj2-4hq8-938g — thanks @RamiAltai and @EQSTLab for the reports.record_mode and raise a clear error on an invalid value (#208)Full Changelog: https://github.com/kevin1024/vcrpy/compare/v8.2.0...v8.2.1
Add support for httpx 2.x (#993) - thanks @dsfaccini
AsyncStreamReaderMixin removed and ClientResponse now requires stream_writer (#995) - thanks @dsfaccinidrop_unused_requests honours before_record_request filtering (#962) - thanks @jamesbrazaVCRHTTPResponse (#976) - thanks @dAnjouconvert_body_to_unicode to use an explicit type check (#982) - thanks @Polandia94Full Changelog: https://github.com/kevin1024/vcrpy/compare/v8.1.1...v8.2.0
Fix sync requests in async contexts for HTTPX (#965) - thanks @seowalex
Enable brotli decompression if available (via brotli, brotlipy or brotlicffi) (#620) - thanks @immerrr
brotli, brotlipy or brotlicffi) (#620) - thanks @immerrrdata and json arguments when one is None (#624) - thanks @leorochaelFull Changelog: https://github.com/kevin1024/vcrpy/compare/v8.0.0...v8.1.0
Fix iscoroutinefunction deprecation warning on Python 3.14 - thanks @kloczek
drop_unused_requests option to remove unused interactions from cassettes (#763) - thanks @danielnsilvahttpx.ResponseNotRead exceptions (#832, #834)KeyError: 'follow_redirects' (#945)iscoroutinefunction deprecation warning on Python 3.14 - thanks @kloczekFull Changelog: https://github.com/kevin1024/vcrpy/compare/v7.0.0...v8.0.0
Drop support for python 3.8 (major version bump) - thanks @jairhenrique
- Drop support for python 3.8 (major version bump) - thanks @jairhenrique
- Various linting and test fixes - thanks @jairhenrique
- Bugfix for urllib2>=2.3.0 - missing version_string (#888)
- Bugfix for asyncio.run - thanks @alekeik1
Ensure body is consumed only once (#846) - thanks @sathieu
Bugfix with to Tornado cassette generator (thanks @graingert)
Bugfix with to Tornado cassette generator (thanks @graingert)
BREAKING: Drop support for boto (vcrpy still supports boto3, but is dropping the deprecated boto support in this release. (thanks @jairhenrique)
boto (vcrpy still supports boto3, but is dropping the deprecated boto support in this release. (thanks @jairhenrique)Use ruff for linting (instead of current flake8/isort/pyflakes) - thanks @jairhenrique
BREAKING CHANGE: Drop support for Python 3.7. 3.7 is EOL as of 6/27/23 Thanks @jairhenrique
HUGE thanks to @hartwork for all the work done on this release!
response.raw.stream() to fix urllib v2 compatassert with raise AssertionError: fixes support for PYTHONOPTIMIZE=1Support urllib3 v1 and v2. NOTE: there is an issue running urllib3 v2 on Python older than 3.10, so this is currently blocked in the requirements. Hop
Support urllib3 v1 and v2. NOTE: there is an issue running urllib3 v2 on Python older than 3.10, so this is currently blocked in the requirements. Hopefully we can resolve this situation in the future. Thanks to @shifqu, @hartwork, @jairhenrique, @pquentin, and @vEpiphyte for your work on this.
Add support for Python 3.11 (Thanks @evgeni)
Fix a bug where the first request in a redirect chain was not being recorded with aiohttp
Drop support for python < 3.7, thanks @jairhenrique, @IvanMalison, @AthulMuralidhar
Fix HTTPX support for versions greater than 0.15 (thanks @jairhenrique)
Add support for httpx!! (thanks @herdigiorgi)
allow_playback_repeats option (thanks @tysonholub)Correct mock imports. Fixes #504
Fix logo alignment for PyPI release
Fix logo alignment for PyPI release
Remove Python2 support (@hugovk)
This release is a breaking change as it changes how aiohttp follows redirects and your cassettes may need to be re-recorded with this update.
aiohttp follows redirects and your cassettes may need to be re-recorded with this update.aiohttp stub #495 (@nickdirienzo)aiohttp stub #495 (@nickdirienzo)Format code with black (@neozenith)
pytest-recording to the documentation as an alternative Pytest plugin (@Stranger6667)Add deprecation warning on python 2.7, next major release will drop python 2.7 support
Nothing published for this version
Support python 3.7 (fix httplib2 and urllib2, thanks @felixonmars)
before_record_response so the original response isn't changed (thanks @kgraves)Fix support to latest aiohttp version (3.3.2).
Fix support to latest aiohttp version (3.2.1)
Nothing published for this version
Allow injection of persistence methods + bugfixes (thanks @j-funk and @IvanMalison) Support python 3.6 + CI tests (thanks @derekbekoe and @graingert)
Allow injection of persistence methods + bugfixes (thanks @j-funk and @IvanMalison) Support python 3.6 + CI tests (thanks @derekbekoe and @graingert) Support pytest-asyncio coroutines (thanks @graingert)
Added a fix to httplib2 (thanks @carlosds730)
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Add support for boto3 (thanks @desdm, @foorbarna).
decode_compressed_response is enabled (thanks @nickdirienzo)Nothing published for this version
Nothing published for this version
[#188] additional_matchers kwarg on use_casstte. [#191] Actually support passing multiple before_record_request functions (thanks @agriffis).
[#188] additional_matchers kwarg on use_casstte. [#191] Actually support passing multiple before_record_request functions (thanks @agriffis).
[#186] Get effective_url in tornado (thanks @mvschaik), [#187] Set request_time on Response object in tornado (thanks @abhinav).
[#186] Get effective_url in tornado (thanks @mvschaik), [#187] Set request_time on Response object in tornado (thanks @abhinav).
Patch fetch_impl instead of the entire HTTPClient class for Tornado (thanks @abhinav).
Patch fetch_impl instead of the entire HTTPClient class for Tornado (thanks @abhinav).
Nothing published for this version
[#169] Support conditional requirements in old versions of pip, Fix RST parse errors generated by pandoc, [Tornado] Fix unsupported features exception
[#169] Support conditional requirements in old versions of pip, Fix RST parse errors generated by pandoc, [Tornado] Fix unsupported features exception not being raised, [#166] content-aware body matcher.
[#120] Tornado support (thanks @abhinav), [#147] packaging fixes (thanks @graingert), [#158] allow filtering post params in requests (thanks @MrJohz),
[#120] Tornado support (thanks @abhinav), [#147] packaging fixes (thanks @graingert), [#158] allow filtering post params in requests (thanks @MrJohz), [#140] add xmlrpclib support (thanks @Diaoul).
1.5.2 Fix crash when cassette path contains cassette library directory (thanks @gazpachoking).
1.5.2 Fix crash when cassette path contains cassette library directory (thanks @gazpachoking).
Nothing published for this version
Nothing published for this version
One column per quarter.