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)   | 
|                  |                            |                  | 
+------------------+                            +------------------+
                                                         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

💡 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

💡 Complete Option Matrix: available here

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

🔧 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: v0.5.0 - Reference management

💡 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
export NO_COLOR=1; excel-vba export      # Via environment variable

💡 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")
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)
open_folder - Open export directory after export (true/false)
keep_open - Keep document open after export (true/false)
no_color - Disable colorized terminal output (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)

Legacy placeholders (deprecated in v0.4.1, removed in v0.5.0):

{general.file.name} → use {file.name}
{general.file.fullname} → use {file.fullname}
{general.file.path} → use {file.path}
{vbaproject} → use {file.vbaproject}

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, with similar functionality)

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 improved header handling, RubberduckVBA folder and config file support in v0.4.0, and unified CLI handling across all Office tools in v0.4.3.

Name		Name	Last commit message	Last commit date
Latest commit History 471 Commits
.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

Folders and files

Latest commit

History

Repository files navigation

vba-edit

Installation

RECOMMENDED: Via uvx (No Install Required)

Python Package

Windows Binaries (No Python Required)

30-Second Demo

How It Works

Why vba-edit?

Setup (One-Time)

VS Code Settings (Recommended)

Common Workflows

Start Fresh

Quick Export with Folder View

Team Project with Git

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

Quick Reference

App-specific tools

Commands

Examples of options

Troubleshooting

Safety Features

Features

Roadmap

💡 Feedback & Contributions

Command Line Tools

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

Colorized Output

Configuration Files

Basic Configuration

Available Configuration Keys

Configuration Placeholders

Command-Line Override

Known Limitations

Links

License

Credits

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 15

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

RECOMMENDED: Via `uvx` (No Install Required)

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

Packages