Installation

VCR.py is a package on PyPI, so you can install with pip:

pip install vcrpy

Compatibility

VCR.py supports Python 2.6 and 2.7, 3.3, 3.4, and pypy.

The following http libraries are supported:

  • urllib2
  • urllib3
  • http.client (python3)
  • requests (both 1.x and 2.x versions)
  • httplib2
  • boto
  • Tornado’s AsyncHTTPClient

Speed

VCR.py runs about 10x faster when pyyaml can use the libyaml extensions. In order for this to work, libyaml needs to be available when pyyaml is built. Additionally the flag is cached by pip, so you might need to explicitly avoid the cache when rebuilding pyyaml.

  1. Test if pyyaml is built with libyaml. This should work:

    python -c 'from yaml import CLoader'
    
  2. Install libyaml according to your Linux distribution, or using Homebrew on Mac:

    brew install libyaml         # Mac with Homebrew
    apt-get install libyaml-dev  # Ubuntu
    dnf install libyaml-dev      # Fedora
    
  3. Rebuild pyyaml with libyaml:

    pip uninstall pyyaml
    pip --no-cache-dir install pyyaml
    

Upgrade

New Cassette Format

The cassette format has changed in VCR.py 1.x, the VCR.py 0.x cassettes cannot be used with VCR.py 1.x. The easiest way to upgrade is to simply delete your cassettes and re-record all of them. VCR.py also provides a migration script that attempts to upgrade your 0.x cassettes to the new 1.x format. To use it, run the following command:

python -m vcr.migration PATH

The PATH can be either a path to the directory with cassettes or the path to a single cassette.

Note: Back up your cassettes files before migration. The migration should only modify cassettes using the old 0.x format.

New serializer / deserializer API

If you made a custom serializer, you will need to update it to match the new API in version 1.0.x

  • Serializers now take dicts and return strings.
  • Deserializers take strings and return dicts (instead of requests, responses pair)

Ruby VCR compatibility

VCR.py does not aim to match the format of the Ruby VCR YAML files. Cassettes generated by Ruby’s VCR are not compatible with VCR.py.