atopile: Design PCBs with Code Using the .ato Language and KiCad

Circuit Board Design as a Software Workflow

Traditional PCB design centers on schematic capture in graphical EDA tools, where an engineer places symbols, draws wires, and assigns component values by clicking through GUI menus. Reuse means copying schematic sections manually; version control means checking in binary files that diff poorly; parameterization means editing values one at a time.

atopile replaces this with a code-based workflow. Engineers write .ato files that declare circuit structure, capture requirements with equations and tolerance assertions, and express component relationships. The atopile compiler reads those files, picks real components from a registry, runs constraint checks, and generates output files including a KiCad PCB file, a bill of materials, and fabrication data.

The README describes the workflow as having seven stages: requirements capture with units and assertions, component selection via parametric picking, design capture in .ato modules and interfaces, layout in KiCad, design rule checking locally or in CI, build output generation, and PCB fabrication. The code layer covers the first five; KiCad handles placement and routing.

Atopile's design philosophy is explicit: the README lists reusable modules, intent capture through equations, and automatic parametric component picking as the core reasons to use it.

The .ato Language: Modules, Interfaces, Units, and Assertions

The .ato language is a declarative language purpose-built for electronics. The README describes its core constructs as modules, interfaces, units, tolerances, and assertions. Modules encapsulate reusable circuit blocks. Interfaces define connection contracts between modules. Units carry physical dimensions, so a voltage specification knows it is in volts and a resistance specification knows it is in ohms. Tolerances allow expressing acceptable ranges rather than exact values. Assertions let engineers encode constraints that the compiler enforces.

The language is compiled using an ANTLR4-based parser, as indicated by the antlr4-python3-runtime dependency pinned at version 4.13.2 in pyproject.toml. ANTLR4 is a parser generator; the atopile team generated the .ato language parser from a grammar and checked the generated files into the repository alongside the grammar.

The README gives ato build as the compile command. Running it updates the .kicad_pcb file, which means the PCB layout file is an output of the build process rather than the source of truth. Circuit structure lives in .ato files; KiCad is the visualization and routing layer.

The documentation site at docs.atopile.io covers the language in depth. The README links specifically to docs.atopile.io/atopile/essentials/1-the-ato-language for the language reference.

Installing atopile in VS Code or Cursor

The README recommends the VS Code extension as the easiest installation path:

https://marketplace.visualstudio.com/items?itemName=atopile.atopile

The extension installs and manages the ato CLI automatically. After installation, the ato menu bar appears in the bottom-left of the VS Code or Cursor window and provides one-click controls for building, opening examples, and launching the PCB layout.

For the quickstart:

1. Install the extension. 2. Run 'atopile: Open Example' in the editor command palette and pick an example. 3. Press the play button in the ato menu bar to build, or run ato build from the terminal. 4. Open the layout in KiCad when ready.

KiCad is not required to run a build. The README notes that builds run and update the .kicad_pcb file without KiCad installed; KiCad is only needed when opening the resulting PCB for layout work.

For CLI installs and advanced setups, the documentation is at docs.atopile.io/atopile/guides/install. The Python package requires Python >=3.14 and strictly less than 3.15, as set in pyproject.toml. This is an unusually narrow version range. The build system also uses nanobind and Zig 0.15.1, which means compiled components are part of the Python package and the install process builds them from source.

For development on atopile itself:

pytest -q

And a fast worktree setup:

ato dev worktree <suffix>
cd ../atopile_<suffix>
source .venv/bin/activate
ato --help

Component Selection and the Package Registry

Parametric component picking is one of atopile's stated core features. Instead of specifying an exact component part number in the schematic, an engineer specifies constraints (resistance value, tolerance, power rating), and the compiler selects a part that satisfies those constraints from a component database.

The package registry at packages.atopile.io provides installable modules: pre-designed circuit blocks that other designers have published. The README describes the workflow as: browse and install modules from the registry, use them in .ato files, and publish your own modules to share with others. The documentation for packages is at docs.atopile.io/atopile/essentials/4-packages, and the publishing guide is at docs.atopile.io/atopile/guides/publish.

The pyproject.toml dependencies include atopile-easyeda2kicad, which suggests the toolchain can import components from EasyEDA (a popular online EDA tool) and convert them to KiCad format for use in designs.

The example projects in the README demonstrate that the toolchain has been used for real hardware designs: a smart speaker (NONOS), a multi-channel DSP board, a Humane Pin-style AI wearable (AI-Pin), a 300,000-nit display for raves (Hyperion), an 18-channel battery cell simulator (Cellsim), and an ESP32 e-paper display driver (ESPaper).

Workflow from .ato Files to Fabrication Data

The README describes the full build pipeline as covering seven high-level steps: requirements capture, component selection, design capture, layout, checks, build output, and PCB fabrication. The atopile toolchain covers the first five; the last two depend on external services.

Checks can run locally or in CI, which means .ato design validation can be integrated into a pull request workflow. This is one of the software-development practices the project explicitly aims to bring to hardware design.

Build outputs include a BOM (bill of materials), fabrication data, and assembly data. These are the files sent to a contract manufacturer. The exact output formats are documented on the documentation site rather than in the README.

The pyproject.toml dependencies include openai>=1.0.0 and mcp[cli]>=1.10.1, indicating the toolchain has integrated AI capabilities. The AGENTS.md and CLAUDE.md files in the repository root, along with the .claude/ and .cursor/ directories, show the development environment includes AI coding assistant configurations. Whether the OpenAI integration is exposed to end users or is internal to development is not documented in the README.

Constraints: Python 3.14 Only, KiCad Dependency, and Early Version

The Python version constraint is the most immediate practical limitation. pyproject.toml specifies requires-python = ">=3.14,<3.15". This means only Python 3.14.x is supported; Python 3.13 and earlier do not work, and Python 3.15 (when released) will not work without a pyproject.toml update. Most Python environments on developer machines may not have 3.14 installed by default, requiring a deliberate Python version management step before installation.

KiCad is required for the layout step. While builds run without it, actually working on the PCB layout requires KiCad. The README says 'KiCad recommended for layout; not required to start.' Teams using other EDA tools (Altium, Eagle, OrCAD) would need to either switch layout tools or export from KiCad.

Windows requires WSL (Windows Subsystem for Linux), which the README explicitly recommends. Native Windows support is not described as a tested path.

The current releases are in the v0.14 series, with v0.14.1004 dated 2026-02-12. The v0.14 version range indicates the project does not yet consider its API stable. The last push was on 2026-06-13. There is no commitment in the README to API stability between releases.

KiCad Scripting as the Alternative for Programmatic Design

KiCad itself includes a Python scripting API that allows programmatic manipulation of schematics and PCB layouts. Engineers can write Python scripts that create footprints, place components, and draw traces. The KiCad scripting API works directly within the KiCad environment and does not require learning a separate language.

The difference from atopile is the level of abstraction. KiCad scripting works at the level of KiCad's internal data model: placing footprints at coordinates, drawing copper pours, running DRC. atopile works at the level of circuit intent: expressing that a resistor should have a certain value within a tolerance and that certain nets should be connected, with the compiler handling component selection and KiCad file updates.

For teams that want to stay entirely within KiCad's ecosystem without learning a new language or toolchain, KiCad scripting is the more direct path. For teams that want the full software-development workflow with version control for design intent, parametric picking, and reusable modules across projects, atopile's approach addresses needs that KiCad scripting does not.

Editorial conclusion

Hardware engineers who want version-controlled, reusable circuit designs and are comfortable working in code will find atopile's approach compelling. The toolchain's narrow Python 3.14 requirement means setup is more involved than a standard pip install, and teams who have invested in other EDA tools will need KiCad for the layout step. The latest release is v0.14.1004 from 2026-02-12. Start with the VS Code extension and the built-in examples at atopile: Open Example before evaluating it for a production design, since the toolchain is still in the v0.14 range and the API changes between releases.

Frequently asked questions

Official sources

1. atopile/atopile on GitHub
2. License: MIT
3. Project website
4. README
5. Releases