{"id":2123,"library":"msgraphfs","title":"Microsoft Graph Filesystem (msgraphfs)","description":"msgraphfs is a Python library that provides a filesystem-like interface to Microsoft Graph drives (SharePoint, OneDrive), built on top of `fsspec`. It enables seamless interaction with Microsoft 365 services, treating remote files and folders as if they were local. The current version, 0.4, introduces URL-based filesystem paths and enhanced multi-site access. The library appears to follow a release cadence driven by feature enhancements and bug fixes, with recent releases addressing usability and pagination.","status":"active","version":"0.4","language":"en","source_language":"en","source_url":"https://github.com/acsone/msgraphfs","tags":["Microsoft Graph","Filesystem","SharePoint","OneDrive","fsspec","Cloud Storage","Azure AD"],"install":[{"cmd":"pip install msgraphfs","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"MSGraphFileSystem","correct":"from msgraphfs import MSGraphFileSystem"}],"quickstart":{"code":"import os\nfrom msgraphfs import MSGraphFileSystem\n\n# Set environment variables for authentication (replace with your actual credentials)\n# Ensure your Azure AD app has 'Sites.Read.All' or 'Files.Read.All' permissions.\n# For more robust production, consider using a credential management system like Azure Key Vault.\nos.environ['MSGRAPHFS_CLIENT_ID'] = os.environ.get('MSGRAPHFS_CLIENT_ID', 'YOUR_CLIENT_ID')\nos.environ['MSGRAPHFS_TENANT_ID'] = os.environ.get('MSGRAPHFS_TENANT_ID', 'YOUR_TENANT_ID')\nos.environ['MSGRAPHFS_CLIENT_SECRET'] = os.environ.get('MSGRAPHFS_CLIENT_SECRET', 'YOUR_CLIENT_SECRET')\n\n# Initialize the filesystem for a specific SharePoint site and drive\n# Replace 'your_sharepoint_site' and 'your_drive_name' with actual values.\n# Alternatively, use URL-based paths directly, e.g., 'msgd://site/drive/path/file'.\ntry:\n    fs = MSGraphFileSystem(\n        protocol=\"sharepoint\",\n        site_name=\"your_sharepoint_site\",\n        drive_name=\"Documents\"\n    )\n\n    # List contents of the root directory\n    print(\"Listing root directory:\")\n    files = fs.ls(\"/\", detail=False)\n    for f in files:\n        print(f)\n\n    # Example: Check if a directory exists and create it if not\n    dir_path = \"/path/to/my/new_folder\"\n    if not fs.isdir(dir_path):\n        print(f\"Directory '{dir_path}' does not exist, creating it...\")\n        fs.mkdir(dir_path)\n        print(f\"Directory '{dir_path}' created.\")\n    else:\n        print(f\"Directory '{dir_path}' already exists.\")\n\n    # Example: Write a simple file\n    file_content = \"Hello from msgraphfs!\"\n    file_path = f\"{dir_path}/test_file.txt\"\n    print(f\"Writing to {file_path}...\")\n    with fs.open(file_path, \"w\") as f:\n        f.write(file_content)\n    print(f\"Content written to {file_path}.\")\n\n    # Example: Read the file\n    print(f\"Reading from {file_path}...\")\n    with fs.open(file_path, \"r\") as f:\n        read_content = f.read()\n    print(f\"Read content: '{read_content}'\")\n\nexcept Exception as e:\n    print(f\"\\nAn error occurred: {e}\")\n    print(\"Please ensure:\")\n    print(\"- Your MSGRAPHFS_CLIENT_ID, MSGRAPHFS_TENANT_ID, and MSGRAPHFS_CLIENT_SECRET environment variables are set.\")\n    print(\"- Your Azure AD application has the necessary API permissions (e.g., Sites.ReadWrite.All or Files.ReadWrite.All).\")\n    print(\"- 'your_sharepoint_site' and 'your_drive_name' are correct for your Microsoft 365 environment.\")\n","lang":"python","description":"This quickstart demonstrates how to initialize `MSGraphFileSystem` using Azure AD application credentials (client ID, tenant ID, client secret) provided via environment variables. It then performs basic filesystem operations like listing directories, creating a new directory, writing a file, and reading a file. An Azure AD application with appropriate permissions (e.g., `Sites.ReadWrite.All`) and correct site/drive names are crucial for successful execution."},"warnings":[{"fix":"Verify Azure AD app registration permissions and consent in the Azure Portal. Double-check `client_id`, `tenant_id`, and `client_secret`. Refer to Microsoft Graph authentication documentation for detailed setup.","message":"Authentication failures (401/403 Forbidden) are common due to incorrect Azure AD application setup. Ensure your application registration in the Azure Portal has the correct API permissions (e.g., `Sites.Read.All` for read-only, `Sites.ReadWrite.All` for read/write access), and that admin consent has been granted. The library uses the client credentials flow for server-to-server authentication.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Standardize on either `MSGRAPHFS_*` or `AZURE_*` prefixes for your environment variables to avoid ambiguity. Prioritize `MSGRAPHFS_*` if there's a conflict, as they are specific to the library.","message":"The 0.4 release introduced fallback support for `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET` environment variables alongside the existing `MSGRAPHFS_*` variables. While convenient, mixing or misconfiguring these can lead to unexpected authentication behavior if both sets are present.","severity":"gotcha","affected_versions":"0.4 and later"},{"fix":"Upgrade to `msgraphfs` version 0.3 or later to ensure all items are returned when listing large folders.","message":"Version 0.3 fixed a pagination bug where listing a folder with more than 200 items (e.g., using `fs.ls()`) would only return the first 200 items, silently truncating the results. Users on versions prior to 0.3 will experience this limitation.","severity":"gotcha","affected_versions":"Prior to 0.3"},{"fix":"Review the documentation for version 0.4 regarding URL-based paths and multi-site access. Adapt your code to use the new protocol prefixes (e.g., `msgd://site/drive/path`) for enhanced flexibility and multi-site support.","message":"Version 0.4 significantly enhanced path handling by introducing URL-based filesystem paths (`msgd://`, `sharepoint://`, `onedrive://` protocols) and enabling a single filesystem instance to access multiple SharePoint sites. While existing explicit `site_name` and `drive_name` initialization might still work, leveraging the new features (especially multi-site or new URL formats) will require updating how paths are constructed and the filesystem is initialized.","severity":"breaking","affected_versions":"0.4 and later"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}