Skip to main content

pyVBAanalysis

PyPI version Python versions Downloads CI Security Malware scan OpenSSF Scorecard License: MIT

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

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.

Metadata

Release files for pyvbaanalysis 3.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyvbaanalysis 3.0.2
File Size Uploaded Provenance Actions
pyvbaanalysis-3.0.2.tar.gz 3.6 MB With provenance Details for pyvbaanalysis-3.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyvbaanalysis 3.0.2
File Interpreter ABI Platform Actions
pyvbaanalysis-3.0.2-py3-none-any.whl Python 3 none any Details for pyvbaanalysis-3.0.2-py3-none-any.whl

Total release size: 6.6 MB

Release files / pyvbaanalysis-3.0.2.tar.gz

Download URL pyvbaanalysis-3.0.2.tar.gz
Size 3.6 MB
Tags Source
SHA-256 checksum
How to use checksums
98473ab07beeb0e179bf3a40058ed611af7e00f96d3e1e9fe27056fdceabed22
BLAKE2b-256 checksum
How to use checksums
111b78f65283943d40cd212a4be329dbb23760d1f8274b55b94f9799c016eaa1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Release files / pyvbaanalysis-3.0.2-py3-none-any.whl

Download URL pyvbaanalysis-3.0.2-py3-none-any.whl
Size 3.0 MB
Tags Python 3
SHA-256 checksum
How to use checksums
d91116510b44f3259f619a9be0a175e7cfa204f157aa7fa6695eff67f8ceef37
BLAKE2b-256 checksum
How to use checksums
1b1fe4e3314116e48a45d4c41a15c11a35752e170df1bf10adea8fe619c0beb9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Security for pyvbaanalysis 3.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pyvbaanalysis-3.0.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page