Installation
============

VCR.py is a package on `PyPI <https://pypi.python.org>`__, so you can install
with pip::

    pip3 install vcrpy

Compatibility
-------------

VCR.py supports Python 3.8+, and `pypy <http://pypy.org>`__.

The following HTTP libraries are supported:

-  ``aiohttp``
-  ``boto3``
-  ``http.client``
-  ``httplib2``
-  ``requests`` (>=2.16.2 versions)
-  ``tornado.httpclient``
-  ``urllib2``
-  ``urllib3``
-  ``httpx``

Speed
-----

VCR.py runs about 10x faster when `pyyaml <http://pyyaml.org>`__ can use the
`libyaml extensions <http://pyyaml.org/wiki/LibYAML>`__. 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::

     python3 -c 'from yaml import CLoader'

2. Install libyaml according to your Linux distribution, or using `Homebrew
   <http://mxcl.github.com/homebrew/>`__ on Mac::

     brew install libyaml         # Mac with Homebrew
     apt-get install libyaml-dev  # Ubuntu
     dnf install libyaml-devel      # Fedora

3. Rebuild pyyaml with libyaml::

     pip3 uninstall pyyaml
     pip3 --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::

    python3 -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.