# 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:

```text
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:

```text
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.

## Import order

Modules are loaded in this order:

1. Root-level personal modules (from `/data/personal` or `/personal`), alphabetically
2. Project-specific modules (from the matching `projects/` subfolder), alphabetically
3. The workbook’s `main.py`

## Limitations

- Personal modules currently don’t offer autocomplete when imported into `main.py`
- Personal modules require a restart after making changes