vba-edit

Enable seamless MS Office VBA code editing in preferred editor or IDE (facilitating the use of coding assistants and version control workflows)

CI PyPI - Version PyPI - Python Version Platform PyPI - Downloads Ruff License

Links

Quickstart

RECOMMENDED: Via uvx (No Install Required)

uvx excel-vba edit -f myfile.xlsm
uvx word-vba edit -f myfile.docm
uvx powerpoint-vba edit -f myfile.pptm
uvx access-vba edit -f myfile.accdb

Note: The uvx command runs the tool without installing it permanently — same as: uv tool run excel-vba

Python Package

pip install -U vba-edit

Windows Binaries (No Python Required)

Standalone executables available – no Python installation needed!

📦 Download: Latest Release (scroll all the way down to Assets section)

Available binaries:

  • excel-vba.exe – For Excel workbooks
  • word-vba.exe – For Word documents
  • access-vba.exe – For Access databases
  • powerpoint-vba.exe – For PowerPoint presentations

Security: See Security Verification Guide for SHA256 checksums and attestation validation.

⚠️ Windows SmartScreen & VirusTotal Warnings: Binaries are currently unsigned. You may see warning messages – this is expected. See Issue #24 and Security Info for details.

Overview command-line tools

Command & Option Reference

Works with word-vba, excel-vba, access-vba, powerpoint-vba — installed or via uvx.

usage: word-vba        [-h] {edit,import,export,check,references} ...
usage: excel-vba       [-h] {edit,import,export,check,references} ...
usage: access-vba      [-h] {edit,import,export,check,references} ...
usage: powerpoint-vba  [-h] {edit,import,export,check,references} ...

Commands

Command Description
edit Live-sync VBA from document to files and back on save
export One-time export of VBA from document to files
import One-time import of VBA from files into document
check Verify ‘Trust access to VBA project object model’ is enabled
references Manage VBA library references — see subcommands below

references subcommands

Subcommand Description
references list List all references in document
references export Export references to TOML file
references import Import references from TOML file (additive)
references import --sync Sync references — add missing, remove extra
references validate Check for broken references (exits 1 if found)
references add LIBRARY Add reference by library file path
references remove NAME Remove reference by name

Complete Option Matrix

Option edit export import Notes
Common
--verbose / -v ✓ ✓ ✓ Verbose logging
--logfile / -l ✓ ✓ ✓ Log to file (default: vba_edit.log)
--no-color / --no-colour ✓ ✓ ✓ Disable colored output
--help / -h ✓ ✓ ✓ Show help
File & Directory
--file / -f ✓ ✓ ✓ Office document path (default: active document)
--vba-directory ✓ ✓ ✓ VBA files directory (default: same as document)
--open-folder ✓ ✓ — Open export directory in Explorer after operation
Configuration
--conf / --config ✓ ✓ ✓ TOML config file path
Encoding (mutually exclusive)
--encoding / -e ✓ ✓ ✓ File encoding (default: cp1252)
--detect-encoding / -d ✓ ✓ ✓ Auto-detect file encoding
Headers (mutually exclusive)
--save-headers ✓ ✓ — Save VBA headers to separate .header files
--in-file-headers ✓ ✓ — Embed VBA headers in code files
Folder Organization
--rubberduck-folders ✓ ✓ ✓ Use RubberduckVBA @Folder subfolder structure
Metadata
--save-metadata / -m ✓ ✓ — Save export metadata to file
Export / Import
--skip-empty — ✓ ✓ Skip modules/files with no code
--with-references ✓ ✓ ✓ Also export/import references TOML alongside VBA
Export-only
--force-overwrite — ✓ — Overwrite existing files without prompting
--keep-open — ✓ — Keep document open after export
Excel only
--xlwings / -x ✓ ✓ ✓ Use xlwings wrapper (Excel only)

Options — references subcommands

Option list export import validate add remove Notes
--file / -f ✓ ✓ ✓ ✓ ✓ ✓ Office document path (default: active document)
--refs-file / -r — ✓ ✓ — — — TOML file (default: {document}_refs.toml)
--sync — — ✓ — — — Make document match TOML exactly (add + remove)
--force-overwrite — — ✓ — — — Allow removing default refs; sync from filtered TOML
--no-default ✓ ✓ — — — — Exclude default refs (VBA, Excel, stdole, etc.)
--no-installed ✓ ✓ — — — — Exclude installed COM library refs
--no-custom ✓ ✓ — — — — Exclude custom file-path refs
LIBRARY (positional) — — — — ✓ — Path to .dotm, .xlam, .dll, .olb, etc.
NAME (positional) — — — — — ✓ Reference name (as shown in references list)
--verbose / -v ✓ ✓ ✓ ✓ ✓ ✓ Verbose logging
--logfile / -l ✓ ✓ ✓ ✓ ✓ ✓ Log to file
--no-color / --no-colour ✓ ✓ ✓ ✓ ✓ ✓ Disable colored output
--help / -h ✓ ✓ ✓ ✓ ✓ ✓ Show help

Examples

# Edit active document (export VBA files, watch for changes, sync back on save)
word-vba edit

# Edit with RubberduckVBA folder structure and embedded headers
word-vba edit --in-file-headers --rubberduck-folders

# Export to a specific directory
word-vba export -f document.docm --vba-directory src/vba

# Import from files with auto-encoding detection
word-vba import -f document.docm --vba-directory src/vba --detect-encoding

# Export using a config file
word-vba export --config myproject.toml --save-metadata

# Edit with verbose logging to file
word-vba edit --vba-directory src/vba --logfile vba.log --verbose

# Export VBA + references in one step
excel-vba export -f workbook.xlsm --with-references

# List all references in active workbook
excel-vba references list

# Export references to a named TOML file
excel-vba references export -r refs/my_refs.toml

# Import references from TOML into a specific file
excel-vba references import -r refs/my_refs.toml -f workbook.xlsm

# Sync references — make document match TOML exactly (default refs protected)
excel-vba references import -r refs/my_refs.toml --sync

# Check for broken references
word-vba references validate -f document.docm

# Add a library reference
word-vba references add C:\Libs\SharedLib.dotm

# Remove a reference by name
word-vba references remove SharedLib