pyACAD authoring guide
Build tools for AutoCAD
Everything you need to turn a folder and a Python file into a button on the AutoCAD ribbon and a command you can type. No compiler, no Visual Studio, no restart.
New here
Start with the quickstart. It gets a working tool on the
ribbon in about five minutes, and every other page assumes you have done it.
pyACAD loads extensions from disk at startup. An extension is a folder
tree whose folder names describe the ribbon: a .tab becomes a ribbon tab, a
.panel becomes a panel on it, and a .pushbutton becomes a button
that runs the script.py inside it. There is no manifest to register, no project
to compile, and no build step. Create the folders, drop in a script, press
Reload.
Every button is also a real AutoCAD command. Click it, type its name at the command line,
put it in a macro or a script file, or call it from AutoLISP with arguments and get a value
back: the tool runs the same way each time, inside the drawing, with one undo step. See
AutoCAD commands and AutoLISP.
These pages document the authoring surface exhaustively: every folder suffix the runtime
recognises, every key it reads out of bundle.yaml, every global it injects into
your script, and every function in the pyacad library. Where the runtime has a
sharp edge, it is called out rather than glossed over.
Start
Bundles
Anatomy of an extensionThe folder levels, how discovery walks them, the files that sit outside a bundle, and the ordering and naming rules that decide what your ribbon looks like.
Buttons, stacks and pulldownsAll twelve bundle kinds: the three a panel holds most often, the nine narrower ones, what each costs in ribbon space, and exactly what each one does when clicked.
The bundle.yaml referenceEvery key the runtime reads from bundle.yaml and extension.yaml, which kinds read it, what it falls back to, and the exact rules of the very small parser that reads the file.
IconsFour PNGs per bundle, how the runtime picks between them for AutoCAD's light and dark themes, and how to draw them so they sit well on the ribbon.
Shortcuts and keytipsKeyboard chords that run a tool without touching the ribbon, the Alt letters that walk to it, and how users rebind both.
Click actions and config.pyOne button, three gestures: a click runs the script, Shift+Click runs the bundle's config.py, Alt+Click opens its folder. Every run goes through an AutoCAD command sent to the drawing.
HooksScripts that run themselves when something happens in AutoCAD, plus the startup.py every extension may carry.
Scripts
The script environmentWhat the runtime does between the click and the first line of your code, every global it hands you, and every rule that follows from it.
Talking to the userToasts, banners, dialogs and pickers, progress, the HTML output window and your own windows: what each one is for, every function's signature, and how they follow AutoCAD's theme.
Settings and per-tool stateEvery key pyACAD reads from config.json, the Settings window that edits them, how a tool remembers its own options, and what lives under %APPDATA%\pyACAD.
AutoCAD commands and AutoLISPEvery tool is an AutoCAD command, so it can be clicked, typed, put in a macro or a script file, or called from AutoLISP with arguments and a return value.
pyacad.exe and headless runsThe pyacad command line: check an install, attach the loader, register extension folders, and run a script over a list of drawings in AutoCAD Core Console.
Reference
Practice
CookbookComplete, runnable recipes for the jobs an AutoCAD tool actually has to do, each with its sharp edge named.
Writing tools with an AI assistantThe Ask AI panel, what it sends and what it writes, and how to get the same result from any chatbot you already use.
TroubleshootingEvery way pyACAD and a bundle fail, listed by what you actually see, with the cause, the fix, and the log line that proves it.
Style guide for toolsThe conventions every shipped tool follows, in code, in look and in behaviour, so that twenty tools written by ten people still feel like one product.