pyVBAanalysis

Static analysis for Office VBA. It reads your macros and reports likely bugs and the errors the VBA compiler would catch, without opening Office or running any code.

Point it at an Excel workbook, a Word document, a PowerPoint deck, an Access database, or a set of exported module files, and it returns the problems it finds, each with the exact line and a plain explanation. Each file is measured against its own host's object model, so Word code is never judged by Excel's surface.

What it checks

It looks for more than a hundred kinds of problem, including:

• Type errors, such as assigning a string to a Long or passing the wrong type to a procedure.
• Undeclared variables and calls to procedures or members that do not exist.
• Code the VBA compiler rejects: duplicate declarations, malformed statements, or a Declare that lacks PtrSafe on 64-bit Office.
• A type from another Office application's library the project does not reference, such as Dim doc As Word.Document in a workbook with no reference to Word.
• Likely run-time failures, such as dividing by a constant zero or a type mismatch from a bad conversion.
• Dead code: variables nothing uses or nothing reads, private procedures nothing calls, and statements no path reaches.

It only reports a problem when it can prove one, and stays quiet otherwise, so the output does not bury you in false alarms.

Install

pip install pyvbaanalysis

Python 3.10 or later. Nothing else to set up.

Use it from Python

Analyze a workbook:

from pyvbaanalysis import analyze_office_file

for module, problems in analyze_office_file("Budget.xlsm").items():
    for p in problems:
        print(module, p.severity.value, p.code, p.message)

Analyze a single module's source:

from pyvbaanalysis import analyze_module

source = "Sub Test()\n    Dim n As Long\n    n = \"oops\"\nEnd Sub\n"
for p in analyze_module(source):
    print(p.code, p.message)

Each result has a code, a message, a severity (error, warning, or information), and a span giving the character offsets in the source.

Analyze several exported files together, so references between them resolve:

from pyvbaanalysis import analyze_loose_files

analyze_loose_files(["Module1.bas", "Sheet1.cls", "UserForm1.frm"])

Use it from the command line

pyvbaanalysis Budget.xlsm
pyvbaanalysis ./exported_modules --format json
pyvbaanalysis Budget.xlsm --only Sheet1

A path can be a workbook, a folder of exported .bas / .cls / .frm files, or a single file. The command exits 1 when it finds problems and 0 when the code is clean, so it drops into a CI check.

The VBE exports files in the Windows code page of the machine that exported them, and that is the page they are read in here by default, unless the file is valid UTF-8. For files exported on a machine in another language, name its page:

pyvbaanalysis ./exported_modules --encoding cp1251

cp1251 is Russian, cp1253 Greek, cp932 Japanese, cp936 Chinese (Simplified). Office files carry their own code page and need no option.

Scope

This analyzes the VBA inside Office files. It does not run macros and does not need Office installed.

Each file is measured against its own host's object model, so a Word document is never judged by Excel's surface. Readable containers: Excel (.xlsm, .xlsb, .xlam, .xls), Word (.docm, .dotm, .doc), PowerPoint (.pptm, .potm, .ppt) and Access (.accdb, .mdb, and the add-ins .accda and .mda, read-only). Excel and Word templates (.xltm, .xlt, .dot), the older Excel add-in (.xla) and PowerPoint shows and add-ins (.ppsm, .ppam, .ppa) are not readable yet: pyOpenVBA does not open them.

Documentation

• Usage guide
• API reference
• Diagnostic catalogue

Built with this

xlide-mcp is an MCP server built on this. The diagnostics here are its build gate: an agent that changes a macro runs them afterwards and treats an error as a failure rather than a suggestion, which is most of what stops a model shipping VBA that does not compile.

Security

Report a vulnerability privately through GitHub's advisory form, not a public issue. CodeQL, Semgrep, pip-audit and a ClamAV and YARA-X malware scan run on every push and daily, and gate every release, and each release carries its security report. See SECURITY.md.

License

MIT. See LICENSE.