VCR.py

Visit Website

Introduction

VCR.py is a Python version of Ruby’s VCR library. The first time code runs inside a VCR.py context manager or decorated function, it records all HTTP interactions through supported libraries and writes them to a flat file, a cassette, in YAML by default. On later runs it reads the cassette and returns the recorded responses for matching requests, so no real HTTP traffic occurs. The README lists the benefits: working offline, completely deterministic tests and faster execution.

Record modes control behaviour: once records only when the cassette is missing, new_episodes adds new interactions, none forbids recording (ideal in CI) and all always re-records. Request matching can be tuned (method, URI, body, headers), and filters remove secrets such as authorisation headers and query tokens before cassettes are saved. VCR.py works with popular HTTP clients, including requests, urllib3, httpx and aiohttp, and the pytest-recording plugin integrates it with pytest via a @pytest.mark.vcr marker. Version 9.4.2 was released on 2 November 2026.

The source code is at kevin1024/vcrpy on GitHub under the MIT licence, with about 3,000 stars; the most recent commit was on 10 November 2026.

Features

1. Record and replay: Real responses captured once, replayed forever.
2. Record modes: once, new_episodes, none and all.
3. Secret filtering: Strip headers, query parameters and body data.
4. Many clients: requests, urllib3, httpx, aiohttp and more.

Pros

1. Free to use: Open source under the MIT licence, so the core tool costs nothing to use.
2. Actively maintained: The repository had commits as recent as 10 November 2026.
3. Community: About 3,000 GitHub stars.

Cons

1. Stale cassettes: Recorded responses drift from the real API over time; re-record regularly.
2. Secrets risk: Forgetting filters can commit credentials to the repository.

Usage and Links (Example)

import requests
import vcr

my_vcr = vcr.VCR(
    cassette_library_dir="tests/cassettes",
    record_mode="once",
    filter_headers=["authorization"],
)

@my_vcr.use_cassette("github_user.yaml")
def test_github_user():
    r = requests.get("https://api.github.com/users/octocat")
    assert r.json()["login"] == "octocat"

In CI, set record_mode="none" so tests fail rather than hitting the network.

Resources:

• VCR.py website
• GitHub repository

Pricing

VCR.py is free and open source under the MIT licence.

Recommended for?

1. Python code calling third-party APIs that should be tested offline.
2. Teams wanting realistic responses without hand-writing stubs.

Conclusion

VCR.py makes HTTP-heavy Python tests fast and deterministic by recording real interactions, provided cassettes are filtered and refreshed.