README.md
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}