pyfakefs

6.1.6 · active · verified Thu Apr 09

pyfakefs implements a fake file system that mocks the Python file system modules. It allows tests to operate on an in-memory file system without touching the real disk, requiring no modification to the software under test. pyfakefs supports pytest, unittest, and can be used as a context manager. It is actively maintained with frequent releases to support new Python versions and fix bugs.

Warnings

breaking pyfakefs version 6.0.0 and above dropped support for Python versions older than 3.10. Ensure your project runs on Python 3.10+ when upgrading.
Fix: Upgrade your Python environment to 3.10 or newer, or pin pyfakefs to a version prior to 6.0.0 (e.g., `pyfakefs<6.0.0`).
breaking Support for patching legacy modules `scandir` and `pathlib2` was removed in pyfakefs version 6.0.0. If your tests relied on these, they will break.
Fix: Migrate your code to use the standard `os.scandir` and `pathlib.Path` modules, which pyfakefs continues to patch.
gotcha pyfakefs cannot mock file system access that uses C libraries directly, rather than Python's standard `os`, `io`, or `pathlib` modules. Libraries like `lxml` fall into this category.
Fix: Avoid using C-backed libraries for file I/O in code under test with pyfakefs, or patch them separately if possible. Consider using pure Python alternatives where applicable.
gotcha Using `unittest.mock.patch` on file system functions concurrently with pyfakefs can lead to incorrect behavior or conflicts, as both attempt to modify the same system modules.
Fix: Prefer using pyfakefs's native patching mechanisms (e.g., `fs` fixture, `TestCase` inheritance, `Patcher`) for file system related mocks. Avoid `unittest.mock.patch` for `os`, `io`, or `pathlib` when pyfakefs is active.
gotcha pyfakefs does not retain the Method Resolution Order (MRO) for its fake file objects. This means `isinstance()` checks against original file types (e.g., `io.TextIOBase`) may fail unexpectedly.
Fix: Avoid using `isinstance()` checks to differentiate file object types when using pyfakefs. Focus on duck typing or attribute checks if necessary.
gotcha pyfakefs is not guaranteed to work correctly in multi-threading environments, especially concerning concurrent write access to a single file from different threads.
Fix: If testing multi-threaded code with file I/O, exercise caution. Consider restructuring tests to isolate file operations or to avoid concurrent access to the same fake files.

Install

pip install pyfakefs Install stable version

Imports

pytest_fixture
```
import pytest
def test_something(fs):
```
The 'fs' fixture is automatically provided by the pyfakefs pytest plugin.
TestCase
```
from pyfakefs.fake_filesystem_unittest import TestCase
```
For unittest integration, inherit from TestCase and call self.setUpPyfakefs() and self.tearDownPyfakefs().
Patcher
```
from pyfakefs.fake_filesystem_unittest import Patcher
```
Use Patcher as a context manager for patching specific blocks of code.
FakeFilesystem
```
from pyfakefs.fake_filesystem import FakeFilesystem
```
For direct programmatic access to the fake filesystem object without a test runner integration.

Quickstart

This example demonstrates basic file operations using the `fs` pytest fixture, which automatically sets up and tears down an in-memory fake filesystem for your test. Simply run `pytest your_test_file.py`.

import os
import pytest

def test_file_operations(fs):
    # The 'fs' fixture provides a fake file system
    # All os.path and file operations will use this fake system
    assert not os.path.exists("/test_dir")
    os.mkdir("/test_dir")
    assert os.path.exists("/test_dir")

    file_path = "/test_dir/my_file.txt"
    with open(file_path, "w") as f:
        f.write("Hello, pyfakefs!")

    assert os.path.exists(file_path)
    with open(file_path, "r") as f:
        content = f.read()
    assert content == "Hello, pyfakefs!"

    os.remove(file_path)
    assert not os.path.exists(file_path)

view raw JSON →