Setup & Requirements

Python Version

LinkCAD 11 ships with an embedded Python 3.12 interpreter. No separate Python installation is required.

Plugin Location

Place Python plugin files (.py) in one of these directories:

User plugins: %APPDATA%\LinkCAD\plugins\
System plugins: <LinkCAD install dir>\plugins\

LinkCAD scans these directories on startup and registers any plugins it finds.

Accessing the Console

Open the interactive Python console from the menu:

View → Python Console (Ctrl+Shift+P)

The console provides full access to the linkcad package and the currently loaded drawing.

Both the console and the script editor define a global named drawing, which always refers to the drawing currently open in LinkCAD, or None when nothing is loaded. It is owned by the application — read and modify it, but never call destroy() on it.

if drawing is not None:
    print(drawing.name, len(drawing.cells), "cells")

A drawing you create yourself must be released, or the interpreter crashes at shutdown. Use it as a context manager:

from linkcad.v1.db import Drawing

with Drawing("scratch") as dwg:
    ...

Script Editor

LinkCAD includes a built-in script editor:

View → Python Script Editor (Ctrl+Shift+E)
Run the current script with F5
Run the selected text with Ctrl+↵

Package Structure

linkcad and linkcad.v1 publish the API’s modules, and nothing else:

Module	Purpose
`linkcad.v1.plugin`	Plugin framework — decorators, options, base classes
`linkcad.v1.db`	Drawing database — cells, layers, shapes, transactions
`linkcad.v1.geom`	Geometry primitives — points, vectors, transforms, bounds
`linkcad.v1.edit`	Geometry tasks — merge, flatten, snap, join, explode
`linkcad.v1.env`	Options and logging — persistent settings, event log
`linkcad.v1.conv`	File format conversion — load and save drawings
`linkcad.v1.libgraph`	Boolean geometry — union, intersection, difference
`linkcad.v1.controller`	High-level conversion workflow controller

A name lives in the module that defines it, so reach for the module first and the names inside it second:

from linkcad import db, geom            # or: from linkcad.v1 import db, geom
from linkcad.v1.db import Drawing, Cell, Layer
from linkcad.v1.geom import Point, Vector

There are no names at the top level: from linkcad import Drawing does not work, and neither does from linkcad.v1 import Drawing.

That is deliberate, not an omission. The modules’ contents collide. FillRule is a different enum in db, edit and libgraph; HolesMode differs between edit and libgraph; CellContext and FormatInfo each name two unrelated types. A flat namespace would have to pick one of each — and would pick it by import order, which is not a rule anyone can predict.

The module list is discovered from the package directory rather than written down, so it can never fall behind. The hand-picked list it replaced named twelve classes and omitted Arc, Ellipse, Donut, Nurbs, Text, Ref, Shape, Object, Property, every enum, and the whole of linkcad.geom.

API Versioning

Prefer the linkcad.v1.* submodules. Each mirrors the whole public namespace of the matching top-level module, so the objects are the same ones; using v1 pins your script to the stable API surface, so it will continue to work as the LinkCAD Python API evolves.

import linkcad

print(linkcad.API_VERSION)   # "v1"
print(linkcad.__version__)   # e.g. "11.0.27" — read from the loaded LinkCAD build

__version__ is not a literal in the package: it comes from linkcad.env.program_version(), so it is always the version of the binary that is actually loaded.

Editor Support

The package ships type stubs and is marked with py.typed (PEP 561), so an editor or type checker understands linkcad.* without any configuration on your part:

completion for cell. and drawing., with the real member list
signature help — cell.add_polygon(layer, vertices) shows both parameters and their types
a red underline for cell.shapes() called as a method, for a str where a Layer goes, and for the None that drawing.cell(name) can return

The stubs are generated from the built modules at build time rather than committed, so they cannot drift from the bindings they describe. If you point your editor at the interpreter LinkCAD ships, or add its site-packages directory to your project’s path, all of the above works with no further setup.

Installing Additional Packages

You can install additional Python packages using pip in the LinkCAD Python environment:

import subprocess
subprocess.check_call(["pip", "install", "numpy"])