Registry / testing / vcrpy
library8.3.0pypypi✓ verified 29d ago

vcrpy (version 8.1.1) is a Python library that automatically mocks your HTTP interactions, making tests faster and more reliable by 'recording' network requests and 'replaying' them from a local file (a 'cassette'). It supports various HTTP libraries like `requests`, `aiohttp`, and `httpx`. The library maintains an active development pace with frequent updates and bug fixes, typically releasing new versions every few months.

pip install vcrpy
INSTALL
IMPORT
SIG · VCRPY
V
vcrpy
testingpythonv8.3.0
Install
2.6s avg
Import
643ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v8.3.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.910 runs
installs and imports cleanly · install 0.0s · import 0.683s · 21.1MB
glibc
py 3.10–3.910 runs
installs and imports cleanly · install 2.6s · import 0.602s · 22MB
20MB installed
● package 20MB
Code
Verified usage

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

VCR
✓ from vcr import VCR
✗ from vcrpy import VCR
The primary module is `vcr`, not `vcrpy`.
use_cassette
✓ import vcr @vcr.use_cassette('cassettes/my_cassette.yaml')
Commonly used directly as a decorator or context manager from the imported `vcr` module.

This quickstart demonstrates how to use `vcrpy` as a context manager with `requests` to record and replay HTTP interactions. The `vcr.VCR()` object is configured to store cassettes in a specified directory. The first run will make a real network request and save it; subsequent runs with the same cassette name will replay the recorded response, speeding up tests and isolating them from network fluctuations.

import vcr import requests def fetch_data(): # Simulate an external API call response = requests.get('http://worldtimeapi.org/api/timezone/America/New_York') response.raise_for_status() return response.json() # Configure VCR to store cassettes in a specific directory my_vcr = vcr.VCR(cassette_library_dir='fixtures/vcr_cassettes') # Use VCR as a context manager to record/replay HTTP interactions with my_vcr.use_cassette('timezone_ny.yaml'): print("Fetching data with VCR...") data = fetch_data() print(f"Current time: {data['datetime']}") # The next time this runs, it will use the recorded cassette if present. print("Fetching data again (should be from cassette if run previously)...") with my_vcr.use_cassette('timezone_ny.yaml'): data = fetch_data() print(f"Replayed time: {data['datetime']}") # Example of clearing a created directory for clean runs (optional) import os import shutil if os.path.exists('fixtures'): print("Cleaning up 'fixtures' directory.") shutil.rmtree('fixtures')
Debug
Known issues
breakingvcrpy v8.0.0 dropped support for Python versions older than 3.10. Users on Python 3.9 or earlier will need to upgrade their Python environment.
fix
Upgrade Python to version 3.10 or newer.
affects: >=8.0.0
breakingvcrpy v8.0.0 dropped support for `urllib3` versions older than 2.0.0. This can cause compatibility issues if your project relies on an older `urllib3` version.
fix
Ensure `urllib3` is updated to version 2.0.0 or newer (e.g., `pip install 'urllib3>=2'`).
affects: >=8.0.0
breakingThe `httpx` integration was significantly rewritten in v8.0.0 to patch `httpcore` directly. This change may require recreation of existing `httpx` cassettes and resolves issues like `httpx.ResponseNotRead` exceptions.
fix
Recreate any `httpx` related cassettes after upgrading. Review `httpx` request patterns if encountering new issues.
affects: >=8.0.0
breakingvcrpy v6.0.0 dropped support for the deprecated `boto` library. `boto3` remains fully supported.
fix
If your project uses `boto`, migrate to `boto3` or pin `vcrpy` to a version older than 6.0.0.
affects: >=6.0.0
gotchaCassettes recorded for `httpx` interactions in versions prior to v6.0.0 might be corrupted or incorrectly saved due to a binary format issue fix.
fix
After upgrading to v6.0.0 or later, it is recommended to recreate all existing `httpx` cassettes.
affects: <6.0.0
gotchaPrior to v8.1.1, there were issues with handling synchronous HTTP requests (especially with `httpx`) when executed within an asynchronous context.
fix
Upgrade to v8.1.1 or newer to ensure correct behavior of sync requests in async contexts with `httpx`.
affects: <8.1.1
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'vcr'
The vcrpy library is not installed in your current Python environment.
fix
Install the library using pip: `pip install vcrpy`
vcr.errors.UnsupportedLibraryError: Unsupported library 'httpx'
vcrpy needs specific extra packages to support certain HTTP client libraries like httpx or aiohttp, which were not installed.
fix
Install vcrpy with the required extra: `pip install "vcrpy[httpx]"` or `pip install "vcrpy[aiohttp]"`
ModuleNotFoundError: No module named 'vcr.stubs.httpx_stubs'
This error occurs when vcrpy attempts to patch httpx but the necessary integration stub for httpx (part of vcrpy's extras) is not installed.
fix
Install vcrpy with the httpx extra: `pip install "vcrpy[httpx]"`
TypeError: use_cassette() missing 1 required positional argument: 'cassette_path'
The `@vcr.use_cassette` decorator or `with vcr.use_cassette()` context manager was called without specifying the required path to the cassette file.
fix
Provide a path to the cassette file: `@vcr.use_cassette('cassettes/my_cassette.yaml')` or `with vcr.use_cassette('cassettes/my_cassette.yaml'):`
vcrpy.errors.CassetteError: Cassette not found: <cassette_path>
The vcrpy library was configured with `record_mode='none'`, but the specified cassette file does not exist.
fix
Ensure the cassette file exists (e.g., by recording it first with `record_mode='new_episodes'`) or change the `record_mode` to allow recording (e.g., `'once'`, `'new_episodes'`, or `'all'`).
Upgrade
Version history
8.3.0latest on PyPI · released Jul 4, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer since v8.0.0.
urllib3requiredRequires urllib3 version 2 or newer since v8.0.0.
Agent activity
23 hits · last 30 days
node
16
OpenAI (training)
1
Resources
vcrpy — pip install vcrpy · libregistry