Formal file spec for .kicad_pcb files?

I’ve searched for more complete info on the new .kicad_pcb format

one link is
but there are no further links under the file extensions, and Documentation is the user-manual level.

I can find chatter that mentions version 4 on, but not links
and of course, there is
(kicad_pcb (version 4)
in every file…

This has glimmers of info
but looks woefully out of date…

I can generate example files by entering data, and saving, but that can miss entities or structures that may be supported.
There must be a link to this somewhere (somewhat off google’s radar…?)

Did you check the kicad repo for this?
And you probably want to get on the mailing list with the devs if you climb that deep into the rabbit hole anyway… might pay to contact one of the more involved people like @cbernardo or @madworm to speed things up with registering.

Only briefly, but the search within there is not great …

hehe, yes, good expression there :slight_smile:

At least this s-expression file format is a dream to work with, and even the parser gives a line# & column#, so I’ve gone quite a ways down that rabbit hole already…

Unfortunately there is nothing which I would consider adequate. If I were to write such documentation though, I would start with the description of the old format (version 2 I believe) and translate the entities into their s-expr equivalent. Then I would painfully go through pcbnew and create objects to verify that the output is as expected. Then I would generate kicad_pcb files or fragments and make sure that pcbnew reads them without problems (read + write == same data even if the actual files are different). One thing to watch out for are peculiarities such as:

(pad 1 thru_hole circle (at 1 0) (size 1.6 1.6) … )
(pad 2 thru_hole oval (at 1 0 45) (size 1.6 2.6) … )

You’d think a “circular” pad should only have one dimension given for the size; also note the third ‘at’ parameter (rotation) which of course makes no sense for a circular pad.

1 Like

Thanks, that’s pretty much what I’ve been doing.
Those items you mention above are easily spotted, less easy are things like…
There seem to be some subset of valid layers for PadStacks, I’m guessing those listed on the Edit choices ? Viz
F.Adhes,B.Adhes, F.Paste,B.Paste,F.SilkS,B.SilkS,F.Mask,B.Mask,Dwgs.User,Eco1.User,Eco2.User

I have blocks and polylines in the source, that I am having to smash into fragments, and that makes me uneasy,
Rather goes against the grain, to lose coherence that was there…
So I was hoping a full file format might include some gems like

  • block structures for combined Lines & Text, and
  • some poly-lines that can support better segment drag. (ie allow lines-edit similar to tracks)

For module definitions there are restrictions on what layers you can put in but I can’t remember if any of those restrictions are actually enforced or if the module editor simply doesn’t allow you to create such entries.

Other restrictions: filled polygons may only appear on a copper layer.
Line/Arc/Circle glyphs can only appear on non-copper layers.

Unfortunately Polylines are not supported; I would like them to be supported and to allow them on copper for fill zones and non-copper for fill zones and outlines. So for now, polylines on non-copper layers must be replaced by an ungrouped mess of lines/arcs. Polylines intended to be fills for a copper layer need to be converted into a simple polygon so you lose any actual arc data in the polyline.

Have fun. By the way, why are you playing around with the file format?

Looking at Translation into KiCad :slight_smile:
See also posts in this thread, covering NET and Trace starting points…

and here is a screen shot, of test cases of padstacks/text/lines translate.


I can import and gerber plot line-items on Copper layers, but I cannot edit/create line items.

I can understand actively discouraging users from placing line items on Copper layers, but 100% prohibition excludes some imports and workarounds.
I thought I had a useful “Are you sure / this is dangerous” message once, but I cannot find that again…

… Some more rules to add…

Yes, doing that now.
In KiCad those fragmented elements make outline and route profile fine editing much more of a pain than it needs to be.
You can nicely drag traces, so the same tools should apply to polylines.

I’ve read ARCs are coming ‘sometime’ - any idea of timelines, and which entities will support ARCS ?
eg PADS allows ARCs in Copper and Pour outlines, and even in Traces, but their Shove router is not arc-aware.

  1. Polylines: doing it right would require substantial changes to kicad’s geometry kernel. At some point I was thinking of entirely replacing the geometry kernel but gave up because there are more urgent things for me to do.

  2. Arcs on copper: Jean-Pierre is working on a custom pad shape; this allows arcs within the pad definitions. For Arc tracks I don’t know if there are any plans/progress.

  3. Broken up Polylines: I agree these are a nuisance. Code such as the IDF exporter has to find all these randomly ordered glyphs then attempt to construct a board outline and cutouts. When using a text editor to inspect the outlines it’s usually impossible for a human to make sense of the list. If we used Polylines then we could ensure that the outline is closed; merging non-self-intersecting Polylines is also trivial so we can still support the tricks which some people like to use such as having a footprint like a board edge connector contain part of the outline of the board.

That sounds very interesting - is there any mailing list on that, or a proposed pad format defined yet ?
‘copper’ here includes Paste & Mask, right ?

I have conventional pad stacks & slots done, but I have paused a little at copper polygons, as D shaped pads are often needed and it would be much better if native support was in kiCad for that.

Will this work also improve the (arc_segments 32) limit ?
I find whilst I can import/save any arc_segments value, <> 32 treats as 16, and does not survive an edit of that entity.