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.
It looks for more than a hundred kinds of problem, including:
- Type errors, such as assigning a string to a
Longor 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
Declarethat lacksPtrSafeon 64-bit Office. - A type from another Office application's library the project does not
reference, such as
Dim doc As Word.Documentin 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.
pip install pyvbaanalysis
Python 3.10 or later. Nothing else to set up.
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"])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.
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.
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.
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.
MIT. See LICENSE.