1# pyfakefs [](https://badge.fury.io/py/pyfakefs) [](https://img.shields.io/pypi/pyversions/pyfakefs.svg)  [](https://pytest-pyfakefs.readthedocs.io/en/latest/?badge=latest) [](https://results.pre-commit.ci/latest/github/pytest-dev/pyfakefs/main) 2 3 4pyfakefs implements a fake file system that mocks the Python file system modules. 5Using pyfakefs, your tests operate on a fake file system in memory without 6touching the real disk. The software under test requires no modification to 7work with pyfakefs. 8 9Pyfakefs creates a new empty in-memory file system at each test start, which replaces 10the real filesystem during the test. Think of pyfakefs as making a per-test temporary 11directory, except for an entire file system. 12 13There are several means to achieve this: by using 14the `fs` fixture if running pytest, by using `fake_filesystem_unittest.TestCase` as a 15base class if using unittest, by using a `fake_filesystem_unittest.Patcher` instance 16as a context manager, or by using the `patchfs` decorator. 17 18 19 20pyfakefs works with current versions of Linux, Windows and macOS. 21 22## Documentation 23 24This document provides a general overview for pyfakefs. There is more: 25 26* The documentation at **Read the Docs**: 27 * The [Release documentation](https://pytest-pyfakefs.readthedocs.io/en/stable) 28 contains usage documentation for pyfakefs and a description of the 29 most relevant classes, methods and functions for the last version 30 released on PyPI 31 * The [Development documentation](https://pytest-pyfakefs.readthedocs.io/en/latest) 32 contains the same documentation for the current main branch 33 * The [Release 3.7 documentation](https://pytest-pyfakefs.readthedocs.io/en/v3.7.2/) 34 contains usage documentation for the last version of pyfakefs 35 supporting Python 2.7 36* The [Release Notes](https://github.com/pytest-dev/pyfakefs/blob/main/CHANGES.md) 37 show a list of changes in the latest versions 38 39## Usage 40The simplest method to use pyfakefs is using the `fs` fixture with `pytest`. 41Refer to the 42[usage documentation](https://pytest-pyfakefs.readthedocs.io/en/latest/usage.html) 43for information on other test scenarios, test customization and 44using convenience functions. 45 46## Features 47Apart from automatically mocking most file-system functions, pyfakefs 48provides some additional features: 49- mapping files and directories from the real file system into the fake filesystem 50- configuration and tracking of the file system size 51- pause and resume of patching to be able to use the real file system inside a 52 test step 53- (limited) emulation of other OSes (Linux, macOS or Windows) 54- configuration to behave as if running as a non-root user while running 55 under root 56 57## Compatibility 58pyfakefs works with CPython 3.8 and above, on Linux, Windows and macOS, and 59with PyPy3. 60 61pyfakefs works with [pytest](http://doc.pytest.org) version 3.0.0 or above, 62though a current version is recommended. 63 64pyfakefs will not work with Python libraries that use C libraries to access the 65file system. This is because pyfakefs cannot patch the underlying C libraries' 66file access functions--the C libraries will always access the real file 67system. Refer to the 68[documentation](https://pytest-pyfakefs.readthedocs.io/en/latest/intro.html#limitations) 69for more information about the limitations of pyfakefs. 70 71## Development 72 73### Continuous integration 74 75pyfakefs is currently automatically tested on Linux, macOS and Windows, with 76Python 3.8 to 3.12, and with PyPy3 on Linux, using 77[GitHub Actions](https://github.com/pytest-dev/pyfakefs/actions). 78 79### Running pyfakefs unit tests 80 81#### On the command line 82pyfakefs unit tests can be run using `pytest` (all tests) or `unittest` 83(all tests except `pytest`-specific ones): 84 85```bash 86$ cd pyfakefs/ 87$ export PYTHONPATH=$PWD 88 89$ python -m pytest pyfakefs 90$ python -m pyfakefs.tests.all_tests 91``` 92 93Similar scripts are called by `tox` and Github Actions. `tox` can be used to 94run tests locally against supported python versions: 95 96```bash 97$ tox 98``` 99 100#### In a Docker container 101 102The `Dockerfile` at the repository root will run the tests on the latest 103Ubuntu version. Build the container: 104```bash 105cd pyfakefs/ 106docker build -t pyfakefs . 107``` 108Run the unit tests in the container: 109```bash 110docker run -t pyfakefs 111``` 112 113### Contributing to pyfakefs 114 115We always welcome contributions to the library. Check out the 116[Contributing Guide](https://github.com/pytest-dev/pyfakefs/blob/main/CONTRIBUTING.md) 117for more information. 118 119## History 120pyfakefs.py was initially developed at Google by Mike Bland as a modest fake 121implementation of core Python modules. It was introduced to all of Google 122in September 2006. Since then, it has been enhanced to extend its 123functionality and usefulness. At last count, pyfakefs was used in over 2,000 124Python tests at Google. 125 126Google released pyfakefs to the public in 2011 as Google Code project 127[pyfakefs](http://code.google.com/p/pyfakefs/): 128* Fork 129 [jmcgeheeiv-pyfakefs](http://code.google.com/p/jmcgeheeiv-pyfakefs/) added 130 [direct support for unittest and doctest](../../wiki/Automatically-find-and-patch-file-functions-and-modules) 131* Fork 132 [shiffdane-jmcgeheeiv-pyfakefs](http://code.google.com/p/shiffdane-jmcgeheeiv-pyfakefs/) 133 added further corrections 134 135After the [shutdown of Google Code](http://google-opensource.blogspot.com/2015/03/farewell-to-google-code.html) 136was announced, [John McGehee](https://github.com/jmcgeheeiv) merged all three Google Code projects together 137[here on GitHub](https://github.com/pytest-dev/pyfakefs) where an enthusiastic community actively supports, maintains 138and extends pyfakefs. In 2022, the repository has been transferred to 139[pytest-dev](https://github.com/pytest-dev) to ensure continuous maintenance. 140
){kind=link}
){kind=link}
){kind=link}
){kind=link}