vba-edit 0.5.0

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

vba-edit

Edit VBA code in VS Code, PyCharm, Wing IDE, or any editor you love. Real-time sync with MS Office apps (support for Excel, Word, PowerPoint & Access). Git-friendly. No more VBA editor pain.

Installation

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 (.xlsm, .xlsb, .xls)
• word-vba.exe - For Word documents (.docm)
• access-vba.exe - For Access databases (.accdb, .mdb)
• powerpoint-vba.exe - For PowerPoint presentations (.pptm)

🔒 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.

30-Second Demo

# Start editing (uses active Excel/Word document) — no install required!
uvx excel-vba edit    # or: uvx word-vba edit

# That's it! Edit the .bas/.cls files in your editor. Save = Sync.

How It Works

                        <--- vba-edit --->

Excel / Word                 COMMANDS              Your favourite
PowerPoint / Access             v                       Editor

+------------------+                            +------------------+
|                  |                            |                  |
|   VBA Project    |   <---   EDIT*   (once ->) |  (e.g. VS CODE)  | 
|                  |                            |                  |     latest
|  (Office VBA-    |          EXPORT      --->  |   .bas           |  <- AI coding-  
|    Editor)       |                            |   .cls           |     assistants
|                  |   <---   IMPORT            |   .frm           |   
|                  |                            |  (.frx binary)   | 
|                  |                            |                  |     optional
|                  |                            |  [.toml]         |  <- support for 
|                  |                            |                  |     references
+------------------+                            +------------------+
                                                         v
                                                +------------------+
                                                |                  |
 * watches & syncs                              |    (e.g. Git)    |
   back to Office                               |  version control |
   VBA-Editor live                              |                  |
   on save [CTRL+S]                             |                  |
                                                +------------------+

Why vba-edit?

• Use YOUR editor - VS Code, PyCharm, Wing IDE, Sublime, Vim, etc. whatever you love
• AI-ready - Use Copilot, ChatGPT, or any coding assistant
• Team-friendly - Share code via Git, no COM add-ins needed
• Real version control - Diff, merge, and track changes properly
• Well-organized - Keep your VBA structured, clean, and consistent

Setup (One-Time)

Windows Only | MS Office

Enable VBA access in Office:

File → Options → Trust Center → Trust Center Settings → Macro Settings

✅ Trust access to the VBA project object model

💡 Can't find it? Run uvx excel-vba check (or excel-vba check if installed) to verify settings

VS Code Settings (Recommended)

To ensure VS Code handles VBA file encoding correctly, add the following to your user settings (%APPDATA%\Code\User\settings.json):

"[vba]": {
    "files.encoding": "windows1252"
},
"files.associations": {
    "*.bas": "vba",
    "*.cls": "vba",
    "*.frm": "vba"
}

💡 Using VS Code Profiles? Add these settings to each profile's settings.json as well.
Change "windows1252" to match the --encoding value you pass to vba-edit if you use a different code page.

Common Workflows

All workflows below work with both excel-vba <command> (installed) and uvx excel-vba <command> (no install required).

Start Fresh

uvx excel-vba edit                # Start with active workbook — no install required!
excel-vba edit                    # If already installed

Quick Export with Folder View

excel-vba export --open-folder    # Export and open in File Explorer
excel-vba export --keep-open      # Export but keep document open for inspection
excel-vba export --no-color       # Export without colorized output

Team Project with Git

excel-vba export --vba-directory ./src/vba
git add . && git commit -m "Updated reports module"

Support for RubberduckVBA Style (big thank you to @onderhold!)

excel-vba edit --rubberduck-folders --in-file-headers

Quick Reference

App-specific tools

CLI Tool	Description
excel-vba	For Excel Workbooks (.xlsm, .xlsb, .xls)
word-vba	For Word documents (.docm)
access-vba	For Access databases (.accdb, .mdb)
powerpoint-vba	For PowerPoint presentations (.pptm)

💡 Use with uvx excel-vba <command> (no install) or excel-vba <command> (if installed). Standalone .exe binaries also available — see Latest Release.

💡 Note: Additional macro-enabled formats (.xltm, .dotm, .potm) are likely supported but not yet tested in this release.

Commands

Command overview	Description
edit	Edit VBA content in Office document
import	Import VBA content into Office document
export	Export VBA content from Office document
check	Check if 'Trust Access to the Office VBA project object model' is enabled
references	Manage VBA library references (list / export / import / validate / add / remove)

💡 Use uvx excel-vba <command> --help (or excel-vba <command> --help if installed) for a detailed option overview.

Examples of options

All examples below work with both excel-vba <command> (installed) and uvx excel-vba <command> (no install required).

Command	What it does
excel-vba edit	Start live editing
excel-vba export	One-time export
excel-vba import	One-time import
excel-vba export --open-folder --keep-open	Export and open folder in explorer, keep document open for inspection
excel-vba export --force-overwrite	Export without confirmation prompts
excel-vba check	Verify status of Trust access to the VBA project object model
excel-vba references list	List all VBA library references in the active workbook
excel-vba references list --no-default	List only installed and custom references
excel-vba references export	Export references to a TOML file for sharing or version control
excel-vba references import -r refs.toml	Restore references from a TOML file
excel-vba references import -r refs.toml --sync	Make document match the TOML file exactly (add missing, remove extra)
excel-vba references validate	Check for broken or missing references
excel-vba references add lib.xlam	Add a reference by file path
excel-vba references remove MyLib	Remove a reference by name
excel-vba export --with-references	Export VBA code and references together

💡 Complete Option Matrix: available here

VBA Reference Manager

Manage VBA library references (e.g. Microsoft Scripting Runtime, ActiveX Data Objects) directly from the command line:

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

# List only installed and custom references (hide defaults)
excel-vba references list --no-default

# Export references to a TOML file (default: {document}_refs.toml)
excel-vba references export
excel-vba references export -r shared_refs.toml

# Import references from a TOML file
excel-vba references import -r shared_refs.toml
excel-vba references import -f myfile.xlsm -r shared_refs.toml

# Sync references — make document match the TOML file exactly
# Adds missing and removes extra references (default refs protected)
excel-vba references import -r shared_refs.toml --sync

# Validate references — check for broken or missing ones
excel-vba references validate

# Add or remove individual references
excel-vba references add path/to/library.xlam
excel-vba references remove "My Custom Library"

Automatic reference sync

Use --with-references to include references alongside code during export, import, or edit:

# Export VBA code AND references together
excel-vba export --with-references

# Import code AND restore references in one step
excel-vba import --with-references

# Live edit with automatic reference sync on save
excel-vba edit --with-references

Reference classification & filtering

References are classified into three categories for easy filtering:

Category	Description	Example
default	Always present in new documents	VBA, Excel, stdole, Office, Normal
installed	Registered COM libraries on the system	Scripting Runtime, Adobe Acrobat
custom	File-path references (no GUID)	Your .docm/.dotm templates

Filter flags can be combined: --no-default, --no-installed, --no-custom

Use cases:

• Track reference dependencies alongside VBA code in version control
• Replicate the same reference setup across multiple documents
• Onboard team members — just run references import to get the right libraries
• Detect broken references before they cause runtime errors

TOML format (exportable and hand-editable):

# GUID-based reference (installed COM library)
[[references]]
name = "Scripting"
guid = "{420B2830-E718-11CF-893D-00A0C9054228}"
major = 1
minor = 0
description = "Microsoft Scripting Runtime"

# Path-based reference (custom template / add-in)
[[references]]
name = "SharedMacros"
path = "\\\\server\\share\\templates\\SharedMacros.dotm"
major = 0
minor = 0

Works with all four Office apps: excel-vba, word-vba, powerpoint-vba, access-vba

Troubleshooting

Issue	Solution
"Trust access" error	Run uvx excel-vba check (or excel-vba check) for diagnostics
Changes not syncing	Save the file in your editor
Forms not working	Add --in-file-headers flag

Safety Features

🛡️ Data Loss Prevention

vba-edit now protects your work with smart safety checks:

• Overwrite Protection: Warns before overwriting existing VBA files
• Header Mode Detection: Alerts when switching between header storage modes
• Orphaned File Cleanup: Automatically removes stale .header files on mode change
• UserForm Validation: Prevents exports without proper header handling

Bypass for Automation: Use --force-overwrite flag to skip prompts in CI/CD pipelines:

excel-vba export --vba-directory ./src --force-overwrite

⚠️ CAUTION: --force-overwrite suppresses all safety prompts. Use with caution!

Features

🚀 Core

• Live sync between Office and your editor
• Full Git/version control support
• All Office apps: Excel, Word, Access & PowerPoint

📁 Organization

• RubberduckVBA folder structure support
• Smart file organization with @Folder annotations
• TOML config files for team standards

📚 Reference Management

• List, export, import, validate, add, and remove VBA library references
• Classify references as default, installed, or custom with composable filters
• Automatic reference sync alongside code with --with-references
• Share reference setups via version-controlled TOML files

🔧 Advanced

• Unicode & encoding support
• UserForms with layout preservation
• Class modules with custom attributes

Roadmap

Development priorities evolve based on user feedback and real-world needs.

👀 See active planning: GitHub Milestones
💡 Request features: Open an Issue
📝 Current focus: Stability, documentation, and exploring PowerQuery support

💡 Feedback & Contributions

Found a bug? Have a feature idea? Questions about usage? Open an Issue - we use labels to organize different types of feedback.

---

Command Line Tools

💡 Complete CLI Overview: available here

Example of --in-file-headers --rubberduck-folders

VERSION 1.0 CLASS
BEGIN
  MultiUse = -1  'True
END
Attribute VB_Name = "MyClass"
Attribute VB_GlobalNameSpace = False
Attribute VB_Creatable = False
Attribute VB_PredeclaredId = False
Attribute VB_Exposed = False

'@Folder("Business.Domain")
Public Sub DoSomething()
    ' Your code here
End Sub

Colorized Output

Terminal output features color-coded messages terms for better readability:

• ✓ Success messages in green
• ✗ Error messages in red
• ⚠ Warning messages in yellow
• Technical terms (VBA, TOML, JSON) highlighted in cyan
• Code examples shown in dim gray

Automatic Behavior:

• Colors automatically disabled when output is piped or redirected
• Disabled in non-TTY environments (CI/CD pipelines)
• Respects NO_COLOR environment variable

Manual Control:

excel-vba export --no-color              # Disable colors
$env:NO_COLOR=1; excel-vba export        # Via environment variable (PowerShell)

💡 Tip: Use --no-color when terminal colors cause issues.

Configuration Files

Use TOML configuration files to standardize team workflows and avoid repetitive command-line arguments.

Basic Configuration

Create a vba-config.toml file in your project:

[general]
file = "MyWorkbook.xlsm"
vba_directory = "src/vba"
verbose = true
rubberduck_folders = true
in_file_headers = true

Then use it:

excel-vba export --conf vba-config.toml

Available Configuration Keys

[general] section:

• file - Path to Office document
• vba_directory - Directory for VBA files
• encoding - Character encoding (e.g., "utf-8", "cp1252")
• detect_encoding - Auto-detect file encoding (true/false)
• verbose - Enable verbose logging (true/false)
• logfile - Path to log file
• rubberduck_folders - Use RubberduckVBA @Folder annotations (true/false)
• save_headers - Save headers to separate .header files (true/false)
• in_file_headers - Embed headers in code files (true/false)
• save_metadata - Save module metadata for reliable reimport (true/false)
• open_folder - Open export directory after export (true/false)
• keep_open - Keep document open after export (true/false)
• skip_empty - Skip modules with no meaningful code (true/false)
• force_overwrite - Overwrite existing files without prompting (true/false)
• with_references - Include VBA references in export/import (true/false)
• no_color - Disable colorized terminal output (true/false)

[references] section:

• refs_file - Path to VBA references file (default: vba-references.toml)
• no_default - Exclude default references from listing (true/false)
• no_installed - Exclude installed COM library references from listing (true/false)
• no_custom - Exclude custom file-path references from listing (true/false)

Other sections (reserved for future use):

• [office] - Office-wide settings
• [excel] - Excel-specific settings
• [word] - Word-specific settings
• [access] - Access-specific settings
• [powerpoint] - PowerPoint-specific settings

Configuration Placeholders

Configuration values support dynamic placeholders for flexible path management.

Available placeholders

• {config.path} - Directory containing the config file
• {file.name} - Document filename without extension
• {file.fullname} - Document filename with extension
• {file.path} - Directory containing the document
• {file.vbaproject} - VBA project name (resolved at runtime)

Example with placeholders:

[general]
file = "C:/Projects/MyApp/MyWorkbook.xlsm"
vba_directory = "{file.path}/{file.name}-vba"
# This resolves to: C:/Projects/MyApp/MyWorkbook-vba

Relative paths example:

[general]
file = "../documents/report.xlsm"
vba_directory = "{config.path}/vba-modules"
# vba_directory is relative to config file location

Command-Line Override

Command-line arguments always override config file settings, including boolean flags:

# Config says vba_directory = "src/vba"
# This overrides it to "build/vba"
excel-vba export --conf vba-config.toml --vba-directory build/vba

# Config says in_file_headers = true
# This overrides it to save-headers mode
excel-vba export --conf vba-config.toml --save-headers

⚠️ CAUTION: 1. Always backup your Office files before using vba-edit 2. Use version control (git) to track your VBA code 3. Run export after changing form layouts or module properties

Known Limitations

• UserForms require --save-headers or newer --in-file-headers option (edit process is aborted if this is not the case)
• If separate *.header files are modified on their own, the corresponding *.cls, *.bas or *.frm file needs to be saved in order to sync the complete module back into the VBA project model

Links

• Homepage
• Documentation
• Source Code
• Changelog
• Changelog of latest dev version
• Video Tutorial (xlwings walkthrough — covers basic edit/export/import concepts; vba-edit has many additional features)

License

BSD 3-Clause License

Credits

vba-edit builds on an excellent idea first implemented for Excel in xlwings (BSD-3).

Special thanks to @onderhold for many valuable contributions since v0.4.0.