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

# Prefer a config file? Open the GUI generator first.
uvx excel-vba config-gen

# 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

Create a Config File

uvx excel-vba config-gen          # Open the config generator GUI
excel-vba export --conf vba-config.toml

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
`config-gen`	Open a GUI to create or edit TOML configuration files
`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 config-gen`	Open the config generator GUI
`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.

You can create them with the built-in GUI instead of writing TOML by hand:

excel-vba config-gen
word-vba config-gen
powerpoint-vba config-gen
access-vba config-gen

The generator provides app-specific file pickers, live TOML preview, and open/save controls for existing or new config files. It is included in the standard install; no extra package is required.

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

The same file can be reused with edit, import, export, and references commands whenever the settings apply.

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.

Name		Name	Last commit message	Last commit date
.github		.github
.vscode		.vscode
LICENSES		LICENSES
packages		packages
src/vba_edit		src/vba_edit
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
AUTHORS.md		AUTHORS.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
SECURITY.md		SECURITY.md
SECURITY_VERIFICATION.md		SECURITY_VERIFICATION.md
create_binaries.py		create_binaries.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation