{"id":7365,"library":"libpff-python","title":"libpff-python","description":"libpff-python provides Python bindings for libpff, an open-source library designed to access Personal Folder File (PFF) and Offline Folder File (OFF) formats, commonly used by Microsoft Outlook for storing emails, contacts, and other data. The current version is 20231205. Releases appear to occur annually or every few years, often coinciding with updates to the underlying C library. [2, 1, 3]","status":"active","version":"20231205","language":"en","source_language":"en","source_url":"https://github.com/libyal/libpff","tags":["forensics","email","PST","PFF","OFF","Outlook","bindings"],"install":[{"cmd":"pip install libpff-python","lang":"bash","label":"Install with pip"},{"cmd":"sudo apt-get install python3-pip libpff-dev\npip3 install pypff","lang":"bash","label":"Debian/Ubuntu with libpff development files"},{"cmd":"brew install libpff\npip3 install pypff","lang":"bash","label":"macOS with Homebrew and pip"}],"dependencies":[{"reason":"This package provides Python bindings for the libpff C library, which must be installed on the system. On Linux, this is typically `libpff-dev` or similar; on macOS, it's available via Homebrew (`brew install libpff`).","package":"libpff (C library)","optional":false}],"imports":[{"note":"The Python module is imported as 'pypff', not 'libpff' or 'libpff-python'.","symbol":"pypff","correct":"import pypff"}],"quickstart":{"code":"import pypff\nimport os\n\ndef process_pst_file(pst_file_path):\n    if not os.path.exists(pst_file_path):\n        print(f\"Error: PST file not found at {pst_file_path}\")\n        return\n\n    try:\n        pst = pypff.file()\n        pst.open(pst_file_path)\n        print(f\"Opened PST file: {pst_file_path}\")\n\n        root_folder = pst.get_root_folder()\n        print(f\"Root folder: {root_folder.get_name()}\")\n\n        def recurse_folders(folder, level=0):\n            indent = \"  \" * level\n            for sub_folder_index in range(folder.get_number_of_sub_folders()):\n                sub_folder = folder.get_sub_folder(sub_folder_index)\n                print(f\"{indent}- Folder: {sub_folder.get_name()}\")\n\n                for message_index in range(sub_folder.get_number_of_sub_messages()):\n                    message = sub_folder.get_sub_message(message_index)\n                    print(f\"{indent}  - Message: {message.get_subject()} (from: {message.get_sender_name()})\")\n                    # Access other message properties, e.g., message.get_body(), message.get_client_submit_time()\n\n                if sub_folder.get_number_of_sub_folders() > 0:\n                    recurse_folders(sub_folder, level + 1)\n\n        recurse_folders(root_folder)\n        pst.close()\n\n    except pypff.libpff.error as e:\n        print(f\"Error processing PST file: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n\n# Example usage:\n# Create a dummy PST file path for demonstration. Replace with your actual PST file.\ndummy_pst_path = os.environ.get('PST_FILE_PATH', 'example.pst')\nprocess_pst_file(dummy_pst_path)\n","lang":"python","description":"This quickstart demonstrates how to open a PST file, navigate its folder hierarchy, and extract basic information such as folder names, message subjects, and sender names. It includes basic error handling for file not found and `libpff` specific errors. [8, 19, 12]"},"warnings":[{"fix":"Review the GitHub issues (e.g., `libyal/libpff` issue #124) for detailed discussions and potential workarounds or API changes. Test thoroughly after upgrading and adapt code to the new binding behavior. [11]","message":"Updating `libpff-python` from version 20211114 to 20231205 introduced breaking changes, specifically affecting methods related to accessing sub-messages and attachments. Applications built with older versions may encounter `OSError` or incorrect data retrieval. [11]","severity":"breaking","affected_versions":"20231205 and later (when upgrading from 20211114 or earlier)"},{"fix":"Install 'Build Tools for Visual Studio' (e.g., 'Desktop development with C++' workload) from Microsoft. Ensure your Python environment can locate these compilers. Alternatively, try to find a pre-compiled wheel for your specific Python version and Windows architecture. [16, 23]","message":"Installation on Windows often fails if the required Microsoft Visual C++ build tools are not installed, leading to compilation errors. This is due to `libpff-python` being a C extension that needs to be compiled. [16, 23]","severity":"gotcha","affected_versions":"All versions on Windows without pre-built wheels"},{"message":"The Python module is imported as `pypff`, not `libpff-python`. Confusingly, there was also a `libpff-python-ratom` package in the past that provided similar functionality but sometimes had more up-to-date features; ensure you are using `libpff-python` and importing `pypff`. [8, 10, 19, 1]","severity":"gotcha"},{"fix":"Pin your `libpff-python` version in `requirements.txt` to avoid unexpected breakage during dependency updates. Be prepared to adapt code when upgrading to newer versions.","message":"The Python bindings (`pypff`) are considered 'work in progress' by maintainers, implying that API stability is not guaranteed and breaking changes can occur with updates. [11]","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify the PST file is valid and not corrupted. Double-check the file path and permissions. Ensure the file is not currently open by another process. [20]","cause":"The PST file specified is either corrupt, not a valid PST file, or the path is incorrect.","error":"OSError: pypff_file_open: unable to open file. libpff_io_handle_read_file_header: invalid file signature."},{"fix":"Install 'Build Tools for Visual Studio' with the 'Desktop development with C++' workload. Ensure environment variables are set correctly for the compiler to be found by Python's build process. [16]","cause":"On Windows, the installation of `libpff-python` requires a C compiler (like MSVC) to build the C extension, and it's not found or configured correctly.","error":"error: subprocess-exited-with-error × Building wheel for libpff-python (pyproject.toml) did not run successfully. │ exit code: 1 ╰─> [5 lines of output] running bdist_wheel running build running build_ext building 'pypff' extension error: Microsoft Visual C++ 14.0 or greater is required."},{"fix":"If encountering this after upgrading to 20231205, you may need to consult the `libyal/libpff` GitHub repository for updated usage patterns or downgrade to the previous stable version (e.g., `pip install libpff-python==20211114`). [11]","cause":"This specific error indicates a breaking change in the `libpff` library or its Python bindings between versions 20211114 and 20231205, where the API for accessing sub-messages changed or became incompatible.","error":"OSError: pypff_folder_get_number_of_sub_messages: unable to retrieve number of sub messages."},{"fix":"Ensure `pip install libpff-python` completed without errors. Activate the correct virtual environment if one is being used. Verify `pypff.py` (or related compiled module) exists in your site-packages directory. [23]","cause":"The `libpff-python` package was not installed successfully, or the Python environment where it was installed is not the one currently being used.","error":"ImportError: No module named 'pypff'"}]}