{"id":7430,"library":"mozfile","title":"mozfile","description":"mozfile is a Python convenience library providing robust file utilities primarily for use in Mozilla's automated testing environments. It offers enhanced replacements for standard library functions like `shutil.move` and `shutil.rmtree`, designed to handle common issues like file locking on Windows. The current stable version is 3.0.0, released in October 2022, with a stable but infrequent release cadence.","status":"active","version":"3.0.0","language":"en","source_language":"en","source_url":"https://firefox-source-docs.mozilla.org/mozbase/mozfile/index.html","tags":["file utilities","testing","mozilla","windows compatibility","shutil replacement"],"install":[{"cmd":"pip install mozfile","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used as a compatibility shim for JSON operations if available, falling back to `stdlib json`. It is an optional dependency.","package":"orjson","optional":true}],"imports":[{"symbol":"extract","correct":"from mozfile import extract"},{"note":"mozfile.move provides enhanced robustness, especially on Windows, by retrying operations on common file access errors.","wrong":"import shutil; shutil.move(...)","symbol":"move","correct":"from mozfile import move"},{"note":"mozfile.remove provides enhanced robustness, especially on Windows, by retrying operations and suppressing errors for non-existent paths (unlike shutil.rmtree).","wrong":"import shutil; shutil.rmtree(...)","symbol":"remove","correct":"from mozfile import remove"}],"quickstart":{"code":"import os\nfrom mozfile import move, remove\n\n# Create some dummy files/directories for demonstration\nif not os.path.exists('test_dir_src'):\n    os.makedirs('test_dir_src')\nwith open('test_dir_src/file1.txt', 'w') as f:\n    f.write('hello world')\n\n# 1. Use mozfile.move to move a file or directory\ntry:\n    print(f\"Moving 'test_dir_src/file1.txt' to 'file1_moved.txt'...\")\n    move('test_dir_src/file1.txt', 'file1_moved.txt')\n    print(f\"'file1_moved.txt' exists: {os.path.exists('file1_moved.txt')}\")\nfinally:\n    # Clean up after move\n    if os.path.exists('file1_moved.txt'):\n        os.remove('file1_moved.txt')\n\n# 2. Use mozfile.remove to recursively delete a directory\n# This version is more resilient to Windows file lock issues\nprint(f\"Removing 'test_dir_src'...\")\nremove('test_dir_src')\nprint(f\"'test_dir_src' exists: {os.path.exists('test_dir_src')}\")\n\n# 3. Demonstrate remove for non-existent path (no error)\nprint(f\"Attempting to remove a non-existent path 'non_existent_dir'...\")\nremove('non_existent_dir')\nprint(\"No error raised, as expected for mozfile.remove on non-existent paths.\")","lang":"python","description":"This quickstart demonstrates the core utilities of `mozfile`: `move` and `remove`. These functions offer enhanced reliability over standard `shutil` operations, particularly in test environments and on Windows where file locking can be problematic. The `remove` function notably does not raise an error if the path does not exist."},"warnings":[{"fix":"Explicitly check `os.path.exists()` before calling `mozfile.remove()` if you need to ensure the path existed, or adjust error handling to account for silent removal of non-existent paths.","message":"Unlike `shutil.rmtree`, `mozfile.remove` will *not* raise an error if the target path does not exist. This can mask issues if your code expects `FileNotFoundError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Thoroughly test existing code after migrating from `shutil` to `mozfile` to ensure compatibility with altered error handling and retry logic, especially for non-Windows environments where `shutil` might be sufficient.","message":"When replacing `shutil.move` or `shutil.rmtree` with `mozfile.move` or `mozfile.remove`, be aware of the altered error handling. While `mozfile` functions are more robust against temporary file locking, they may behave differently in edge cases or with specific error types.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult `mozbase`'s official documentation and conduct comprehensive regression testing when upgrading to 3.0.0 from older major versions to identify any subtle behavior changes.","message":"The jump from version 2.x to 3.0.0 (released October 2022) for `mozfile`, after a long gap, may include undocumented breaking changes, even if the primary API for core functions like `move` and `remove` appears stable. Always review release notes or test thoroughly when upgrading across major versions.","severity":"breaking","affected_versions":"2.x to 3.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Use `mozfile.move()` or `mozfile.remove()` instead of `shutil.move()` or `shutil.rmtree()`. `mozfile` includes retry logic for such errors, significantly improving reliability in these situations.","cause":"Attempting to move or remove files/directories on Windows that are still locked by another process or application (e.g., explorer, antivirus). Standard `shutil` functions often fail in this scenario.","error":"[WinError 32] The process cannot access the file because it is being used by another process:"},{"fix":"Switch to `mozfile.move()` or `mozfile.remove()`. These functions are designed to mitigate these common permission/access denial issues by retrying the operation with a delay.","cause":"Similar to `WinError 32`, this often occurs when trying to modify or delete files/directories without sufficient permissions or when they are temporarily held by another process. This is common in automated testing environments.","error":"[Errno 13] Permission denied:"}]}