Personal Modules

Personal modules are Python files and packages shared across all your workbooks, similar to VBA’s Personal.xlsb. They let you define scripts and custom functions that are available in every workbook you open. Personal modules are also importable in the workbook’s main.py. Since the files are stored on your machine, you can track them with Git or sync them using OneDrive or a similar service.

Setup

Create a personal folder on your local computer in the following style:

personal/
    accounting.py
    utils.py
    mypackage/
      __init__.py
      other.py

Then go to Menu > Files. Now either

  • upload the folder via drag and drop under Import/Export or

  • mount the folder as /personal under Local Folders (requires Desktop Excel on Windows)

Note

After uploading files or changing files in the mounted folder, you need to restart xlwings Lite by going to Menu > Restart.

After restarting xlwings Lite, the scripts defined in the personal modules will appear in the Run button dropdown and the custom functions will be available in your workbook.

Projects: Workbook-specific modules

If you have modules that should only be available for specific workbooks, place them in a projects subdirectory:

personal/
    utils.py              ← available to all workbooks
    projects/
        sales_report/       ← only for workbooks matching "sales_report"
            __init__.py
            charts.py
        monthly_review/     ← only for workbooks matching "monthly_review"
            analysis.py

The project directory name is fuzzy-matched against the workbook filename:

  • Both names are normalized: the file extension is stripped, spaces are converted to underscores, and everything is lowercased.

  • A project directory matches if its normalized name is contained in the normalized workbook name.

For example, the project directory sales_report matches all of these workbooks:

  • Sales_Report.xlsx

  • 2025_01_15_sales_report_v2.xlsx

  • sales report Q1.xlsx

  • Sales_Report_John.xlsx

Modules placed directly in personal are always loaded regardless of the workbook name. Modules in personal/projects are loaded in addition to the global ones when the workbook name matches.

Limitations

  • Personal modules currently don’t offer autocomplete when imported into main.py

  • Personal modules require a restart after making changes