How to install a symbol & footprint that I downloaded

user40 · July 28, 2025, 4:54am

I need a 10-pin ARM programming connector (FTSH-105-01-L-DV-K) on my board. So I downloaded a KiCad 6+ model of the connector from ultralibrarian.com. Seeing as there are no installation instructions, I copied the symbol file to /usr/share/kicad/symbols/Samtec_FTSH.kicad_sym because I see many other symbols in that folder. I also installed the footprint folder in /usr/share/kicad/footprints/Samtec_FTSH.pretty because I see many other footprints in that folder.

However, the symbol does not appear in the list when I click Place Symbols in the schematic. Restarting kicad does not cause the symbol to appear.

What is the secret incantation to make new symbols and footprints work in KiCad?

jmk · July 28, 2025, 5:37am

Symbols (and footprints) downloaded or created need to be placed in Personal Libraries so they can be accessed to use in Schematics (or PCBs).

This FAQ , I think, should explain how to create Personal Symbol and Footprint Libraries.

If you have problems understanding please ask questions.

Edit: For a symbol, any 10 pin connector will do the job. All you need to do is call it a FTSH etc.
There are a number available in Kicad Connector Libraries. eg. Connector > Con_01X10_Pin.

The footprint will either need to be downloaded or created, so a Personal Footprint Library will need to be created for this.

RaptorUK · July 28, 2025, 8:53am

Why not use this ?

It’s already in KiCad . . .

Piotr · July 28, 2025, 9:11am

“Since always” I’m using only my libraries so don’t believe 100% in what I write about KiCad libraries.
Symbol libraries are files containing many symbols so you should let KiCad insert new symbol into it.
Footprint libraries are directories containing files (each footprint - separate file).
When I want to add to my libraries a footprint from KiCad library I just copy (using file manager) a footprint file from KiCad libraries into my libraries.
I use only defined by me symbols. I start any new symbol making Save-As of another symbol from my library.
Even KiCad libraries are read only I suppose (didn’t checked if) that if system will allow you to copy footprint file into KiCad library you should have it. But when uninstalling KiCad (I always un-install previous version before installing new one) I suppose the whole library is deleted and not file by file so together with it your new footprint will also be deleted.

paulvdh · July 28, 2025, 10:07am

Maybe read the manual, or a tutorial?
The section about library management should do it.

user40 · July 29, 2025, 1:06am

That would be nice. However in KiCad 9.0.1 I typed “PinHeader_” in the search box and it came up empty. Which is odd because I have the file
/usr/share/kicad/footprints/Connector_PinHeader_1.27mm.pretty/PinHeader_2x10_P1.27mm_Vertical.kicad_mod
on my system. I guess this doesn’t save me from having to learn the proper library setup stuff that I’m missing.

RaptorUK · July 29, 2025, 6:53am

@user40 Can you show a screen grab please ? which search box exactly ? with or without quotes ( " " ) ?

Paul.Blitz · July 29, 2025, 3:41pm

Silly question: are you ACTUALLY loading the relevant library? Ages ago I de-selected a LOAD of non-relevant libraries to make things load a lot quicker, maybe you did that too?

user40 · July 30, 2025, 3:59am

A search box comes up when I click “Place Symbols” in the schematic toolbar. The closest it gets to “PinHeader_” is some 2.54mm footprints (see image below). There are no 1.27mm footprints even though I can see the files in /usr/share/kicad.

user40 · July 30, 2025, 4:11am

Silly question: are you ACTUALLY loading the relevant library? Ages ago I de-selected a LOAD of non-relevant libraries to make things load a lot quicker, maybe you did that too?

All of the boxes are checked in Preferences → Manage Symbol Libraries… Though I noticed that it only seems to find .kicad_sym files, while PinHeader_ is .kicad_mod files. And it’s not finding the /usr/share/kicad/symbols/Samtec_FTSH.kicad_sym file that I installed. It is showing lots of files relative to a non-existent (blank) $(KICAD7_SYMBOL_DIR) path variable. $(KICAD9_SYMBOL_DIR) points to /usr/share/kicad/symbols, but it’s not picking anything up from that directory (if you believe the list that it displays).

At this point I’m not understanding how so many people are finding KiCad to be more intuitive than Eagle. In Eagle you literally just set some paths and put the .lbr file there… and it had integrated autorouter. Anyways Eagle is sadly going away so I need to learn KiCad. Hopefully the rough edges get smoothed out.

user40 · July 30, 2025, 4:21am

Thanks for the tutorial link. OK, some progress. I added the following line to my ~/.config/9.0/sym-lib-table file.

(lib (name "Samtec_FTSH")(type "KiCad")(uri "${KICAD9_SYMBOL_DIR}/Samtec_FTSH.kicad_sym")(options "")(descr "Samtec 1.27mm connectors"))

And I added the following line to my ~/.config/9.0/fp-lib-table file.

(lib (name Samtec_FTSH)(type KiCad)(uri ${KICAD9_FOOTPRINT_DIR}/Samtec_FTSH.pretty)(options "")(descr "Samtec 1.27mm connectors"))

Now I see the symbol in “Place Symbols”. But there are no footprints and it says “Invalid footprint specified”. (What is all this business with KICAD7 vs KICAD9? Hopefully that’s not related to my problem.)

What does “invalid” mean here? Can KiCad elaborate on this? I mean, I looked at the footprint file that I downloaded, and to my eye it looks basically like the other footprint files that came with KiCad. Here are the actual contents:

(footprint "CON10_2X5_DUK_FTSH_SAI" (version 20211014) (generator pcbnew)
  (layer "F.Cu")
  (tags "FTSH-105-01-L-DV-K ")
  (attr smd)
  (fp_text reference "REF**" (at 0 0 unlocked) (layer F.SilkS)
    (effects (font (size 1 1) (thickness 0.15)))
  )
  (fp_text value CON10_2X5_DUK_FTSH_SAI (at 0 0 unlocked) (layer F.Fab)
    (effects (font (size 1 1) (thickness 0.15)))
  )
  (fp_text user "${REFERENCE}" (at 0 0 unlocked) (layer F.Fab)
    (effects (font (size 1 1) (thickness 0.15)))
  )
  (fp_poly (pts
      (xy 2.413 2.7305)
      (xy 2.413 3.1115)
      (xy 2.667 3.1115)
      (xy 2.667 2.7305)
    ) (layer "F.SilkS") (width 0) (fill solid))
  (fp_line (start -3.175 2.54) (end -3.175 -2.54) (layer "F.CrtYd") (width 0.1524))
  (fp_line (start -3.175 -2.54) (end -2.7432 -2.54) (layer "F.CrtYd") (width 0.1524))
  (fp_line (start -2.7432 -2.54) (end -2.7432 -3.429) (layer "F.CrtYd") (width 0.1524))
  (fp_line (start -2.7432 3.429) (end 2.7432 3.429) (layer "F.CrtYd") (width 0.1524))
  (fp_line (start 2.7432 -3.429) (end 2.7432 -2.54) (layer "F.CrtYd") (width 0.1524))
  (fp_line (start 2.7432 -2.54) (end 3.175 -2.54) (layer "F.CrtYd") (width 0.1524))
  (fp_line (start 3.175 -2.54) (end 3.175 2.54) (layer "F.CrtYd") (width 0.1524))
  (fp_line (start 3.175 2.54) (end 2.7432 2.54) (layer "F.CrtYd") (width 0.1524))
  (fp_line (start 2.7432 2.54) (end 2.7432 3.429) (layer "F.CrtYd") (width 0.1524))
  (fp_line (start 2.7432 -3.429) (end -2.7432 -3.429) (layer "F.CrtYd") (width 0.1524))
  (fp_line (start -2.7432 3.429) (end -2.7432 2.54) (layer "F.CrtYd") (width 0.1524))
  (fp_line (start -2.7432 2.54) (end -3.175 2.54) (layer "F.CrtYd") (width 0.1524))
  (fp_line (start -2.5019 3.76174) (end -1.905 4.95554) (layer "F.SilkS") (width 0.1524))
  (fp_line (start -1.905 4.95554) (end -3.175 4.95554) (layer "F.SilkS") (width 0.1524))
  (fp_line (start -3.175 4.95554) (end -2.5781 3.76174) (layer "F.SilkS") (width 0.1524))
  (fp_line (start -2.54 3.68554) (end -1.905 4.95554) (layer "F.Fab") (width 0.0254))
  (fp_line (start -1.905 4.95554) (end -3.175 4.95554) (layer "F.Fab") (width 0.0254))
  (fp_line (start -3.175 4.95554) (end -2.54 3.68554) (layer "F.Fab") (width 0.0254))
  (fp_text user "2" (at -3.683 -2.032 unlocked) (layer "F.SilkS")
    (effects (font (size 1 1) (thickness 0.15)))
  )
  (fp_text user "2" (at -3.683 -2.032 unlocked) (layer "F.Fab")
    (effects (font (size 1 1) (thickness 0.15)))
  )
  (fp_text user "1" (at -3.683 2.032 unlocked) (layer "F.SilkS")
    (effects (font (size 1 1) (thickness 0.15)))
  )
  (fp_text user "1" (at -3.683 2.032 unlocked) (layer "F.Fab")
    (effects (font (size 1 1) (thickness 0.15)))
  )
  (fp_text user "10" (at 3.683 -2.032 unlocked) (layer "F.SilkS")
    (effects (font (size 1 1) (thickness 0.15)))
  )
  (fp_text user "10" (at 3.683 -2.032 unlocked) (layer "F.Fab")
    (effects (font (size 1 1) (thickness 0.15)))
  )
  (fp_text user "9" (at 3.683 2.032 unlocked) (layer "F.SilkS")
    (effects (font (size 1 1) (thickness 0.15)))
  )
  (fp_text user "9" (at 3.683 2.032 unlocked) (layer "F.Fab")
    (effects (font (size 1 1) (thickness 0.15)))
  )
  (fp_line (start 3.302 2.667) (end 3.302 -2.667) (layer "F.SilkS") (width 0.1524))
  (fp_line (start -3.302 -2.667) (end -3.302 2.667) (layer "F.SilkS") (width 0.1524))
  (fp_line (start -3.175 2.54) (end 3.175 2.54) (layer "F.Fab") (width 0.0254))
  (fp_line (start 3.175 2.54) (end 3.175 -2.54) (layer "F.Fab") (width 0.0254))
  (fp_line (start 3.175 -2.54) (end -3.175 -2.54) (layer "F.Fab") (width 0.0254))
  (fp_line (start -3.175 -2.54) (end -3.175 2.54) (layer "F.Fab") (width 0.0254))
  (pad "1" smd rect (at -2.54 2.032) (size 0.762 2.794) (layers "F.Cu" "F.Paste" "F.Mask"))
  (pad "2" smd rect (at -2.54 -2.032) (size 0.762 2.794) (layers "F.Cu" "F.Paste" "F.Mask"))
  (pad "3" smd rect (at -1.27 2.032) (size 0.762 2.794) (layers "F.Cu" "F.Paste" "F.Mask"))
  (pad "4" smd rect (at -1.27 -2.032) (size 0.762 2.794) (layers "F.Cu" "F.Paste" "F.Mask"))
  (pad "5" smd rect (at 0 2.032) (size 0.762 2.794) (layers "F.Cu" "F.Paste" "F.Mask"))
  (pad "6" smd rect (at 0 -2.032) (size 0.762 2.794) (layers "F.Cu" "F.Paste" "F.Mask"))
  (pad "7" smd rect (at 1.27 2.032) (size 0.762 2.794) (layers "F.Cu" "F.Paste" "F.Mask"))
  (pad "8" smd rect (at 1.27 -2.032) (size 0.762 2.794) (layers "F.Cu" "F.Paste" "F.Mask"))
  (pad "9" smd rect (at 2.54 2.032) (size 0.762 2.794) (layers "F.Cu" "F.Paste" "F.Mask"))
  (pad "10" smd rect (at 2.54 -2.032) (size 0.762 2.794) (layers "F.Cu" "F.Paste" "F.Mask"))
)

The other preinstalled footprint files are also “version 20211014”. How could there be an incompatibility then?

user40 · July 30, 2025, 4:54am

Update

Someone else encountered a similar situation when downloading a footprint file from UltraLibrarian. I looked here for clues:

However their issue was that the “Footprint” property (in the symbol file) didn’t match the footprint filename, or had a slash, or they had an old KiCad (v6). None of these situations applies in my case. The footprint property in my symbol file is “CON10_2X5_DUK_FTSH_SAI” and the name of my footprint file is “CON10_2X5_DUK_FTSH_SAI.kicad_mod”. My KiCad is v9. So this is not my issue.

Could there be something going on with these suspicious KICAD7 and KICAD9 environment variables? (suspicious in the sense that their existence implies that I’m supposed to know which one to use, when ultralibrarian just said “KiCad 6+” and the files themselves make no mention of v7 or v9) But I tried both variables and the result was the same: symbol found, but footprint is “invalid”.

paulvdh · July 30, 2025, 6:05am

Footprint libraries have to be added to the fp-lib-table file in a very similar way that symbols have to be in a library and the libraries have to be added to the sym-lib-table file. And the footprint link in the symbol does have to have both the correct library name and footprint name.

RaptorUK · July 30, 2025, 6:36am

Symbols are symbolic, Footprints are real.

Your symbol just needs to show 20 pins to connect to . . . the footprint needs to be of the real component where it connects to the PCB pads…

jmk · July 30, 2025, 9:44am

@user40

The Kicad way is to:

Create a Personal Symbol Library
Create a new symbol by making from scratch or importing from Kicad or Elsewhere and perhaps modifying.
Create a Personal Footprint Library.
Create a new footprint by making from scratch or importing from Kicad or Elsewhere and perhaps modifying.

Next: Associate the Footprint with the Symbol by either:
Open the symbol in the Symbol Editor, open the symbol properties (red arrow) and place the link to your footprint in your Personal Footprint Library (yellow arrow).

This will permanently attach your footprint to your symbol (until you maybe wish to change the footprint one day in the future).

OR

Open the Symbol Properties while you are placing or after you have placed the symbol on the schematic.
This will attach your footprint to this one symbol on this one schematic.

Also worth considering is changing your Personal Library to something more generic, eg “User40_Connectors” .
Giving your Personal Library the name of a single connector leaves little room to place a second or third or however many more specialized connectors you will need to create or import over the coming years.

user40 · July 30, 2025, 1:51pm

Footprint libraries have to be added to the fp-lib-table file in a very similar way that symbols have to be in a library and the libraries have to be added to the sym-lib-table file. And the footprint link in the symbol does have to have both the correct library name and footprint name.

Aha! The file that I downloaded from ultralibrarian was missing the library name in the footprint link. Looking at some other examples, it needs to be added to the “Footprint” property and must precede the footprint name with a colon. In other words:

    (property "Footprint" "Samtec_FTSH:CON10_2X5_DUK_FTSH_SAI" (id 2) (at 0 0 0)
      (effects (font (size 1.27 1.27) italic) hide)

Now I am finally able to add the debug connector to my schematic. So I can at least get started. As others have noted, I’ll eventually want to create my own library so that my symbols & footprints don’t get nuked the next time I upgrade KiCad.

paulvdh · July 30, 2025, 3:50pm

You have listed several sections of KiCad’s files. Why? For generic use it’s not recommended to tinker with these files. In these modern times (nearly) everything can be done from within the GUI, and this also makes it easier to follow tutorials.