How to Generate Pick-and-Place Files from KiCad: Complete Guide for PCB Assembly

Every PCB engineer hits this moment eventually: your design is done, Gerbers are ready, and then the assembly house asks for a “position file” or “centroid file.” If you’re using KiCad, generating this pick-and-place file is straightforward once you know the right settings—but getting those settings wrong can lead to misaligned components, rotated ICs, and expensive rework.

I’ve been using KiCad since version 4, and the pick-and-place workflow has improved dramatically over the years. KiCad 8 especially has streamlined the process. This guide walks you through generating position files correctly, avoiding common rotation issues, and formatting your output for popular assembly services like JLCPCB and PCBWay.

What is a Pick-and-Place File in KiCad?

In KiCad terminology, the pick-and-place file is called a “Footprint Position File” and uses the .pos extension. This file contains the exact coordinates and rotation angles that automated assembly machines need to place surface mount components onto your PCB.

When you submit a board for professional assembly, the pick-and-place machine reads this file to determine each component’s X and Y position relative to a reference point, the rotation angle in degrees, which side of the board the component belongs on, and the reference designator matching your schematic.

Key Data Fields in a KiCad Position File

Every position file generated from KiCad includes these essential columns:

Field	Description	Example
Ref	Reference designator from schematic	C1, R15, U3
Val	Component value	100nF, 10K, STM32F103
Package	Footprint name	0805, SOIC-8, TQFP-48
PosX	X coordinate from origin	25.4000
PosY	Y coordinate from origin	-12.7000
Rot	Rotation angle in degrees	0.0000, 90.0000, 180.0000
Side	Board layer	top or bottom

The coordinates are measured in millimeters or inches from the drill/place file origin you set in your PCB layout.

Setting Up the Drill/Place File Origin

This step is critical, and skipping it is the most common mistake I see from engineers new to KiCad. If you don’t set a proper origin, your coordinates will be measured from the default page origin—which sits somewhere in the upper left corner of the drawing sheet, nowhere near your actual board.

How to Place the Origin Correctly

Open your PCB layout in KiCad’s PCB Editor (Pcbnew). Navigate to Place → Drill/Place File Origin from the menu bar. You can also access this from the right toolbar—look for the crosshair icon or long-press to reveal the origin placement tools.

Click to place the origin at the lower-left corner of your board outline. It doesn’t need to be perfectly aligned with the edge, but placing it close to the corner makes your coordinates intuitive and easier to verify.

Once placed, you’ll see a small crosshair marker indicating the origin location. This point becomes coordinate (0, 0) for all your generated position and drill files.

Why the Origin Location Matters

Assembly houses program their pick-and-place machines using your coordinate data. If your origin sits at some arbitrary point on the drawing sheet, all your component positions will be offset by that amount. Some manufacturers can compensate for this, but many will simply assemble the board with everything shifted—resulting in components placed off their pads.

Placing the origin at the board’s lower-left corner follows industry convention and makes troubleshooting much easier when you need to verify coordinates against your layout.

Generating Position Files in KiCad 8

The process has been refined in KiCad 8, making it more intuitive than earlier versions. Here’s the step-by-step workflow.

Step-by-Step Generation Process

With your PCB layout open in the PCB Editor, go to File → Fabrication Outputs → Footprint Position (.pos) File. This opens the Generate Footprint Position Files dialog.

Configure the following settings in the dialog:

Format: Select CSV for most assembly houses. The CSV format opens cleanly in Excel and is universally accepted. ASCII format works too but is less common.

Units: Choose Millimeters. Metric is the international standard, and most modern assembly equipment works natively in millimeters. Only use inches if your manufacturer specifically requests it.

Files: Select your preference between “Single file for board” or “Separate files for front and back.” Most manufacturers accept either format. JLCPCB, for example, works fine with a single combined file.

Include footprints with SMD pads only: For most assembly jobs, enable this option. It excludes through-hole components that won’t be placed by the pick-and-place machine.

Include footprints with through hole pads: Enable this if your assembly house is also handling through-hole insertion.

Use drill/place file origin: Always enable this option. It ensures coordinates reference the origin you placed rather than the default page corner.

Click Generate Position File to create the output.

Understanding the Output File Structure

KiCad generates files named like YourProject-top-pos.csv and YourProject-bottom-pos.csv (or a combined file if you selected that option). Opening the file in a text editor or spreadsheet shows something like this:

Ref,Val,Package,PosX,PosY,Rot,SideC1,100nF,0805,5.0800,3.8100,0.0000,topC2,10uF,0805,8.8900,3.8100,180.0000,topR1,10K,0402,12.7000,6.3500,90.0000,topU1,STM32F103,LQFP-48,25.4000,25.4000,0.0000,top

Each row represents one component with all the information needed for placement.

Configuring Position File Settings for Different Manufacturers

Different assembly services have different requirements. Here’s how to configure your KiCad output for the most popular services.

Position File Settings Comparison by Manufacturer

Setting	JLCPCB	PCBWay	Seeed Studio	Generic
Format	CSV	CSV or TXT	CSV	Either
Units	Millimeters	Millimeters	Millimeters	Either
Files	Single or Separate	Either	Separate	Either
Header Row	Required	Required	Required	Required
Origin	Board corner	Board corner	Board corner	Board corner

Formatting for JLCPCB Assembly Service

JLCPCB has specific requirements for their Component Placement List (CPL) file. While KiCad’s native output works, some column renaming improves compatibility.

JLCPCB expects these column headers: Designator, Mid X, Mid Y, Layer, and Rotation. KiCad outputs: Ref, PosX, PosY, Side, and Rot. Most of the time, JLCPCB’s system automatically maps these, but if you encounter issues, rename the columns in Excel before uploading.

Additionally, JLCPCB uses LCSC part numbers for component matching. Adding an “LCSC” field to your schematic symbols and including it in your BOM significantly speeds up the ordering process.

The KiCad Rotation Problem and How to Fix It

If you’ve used KiCad with assembly services before, you’ve probably encountered the rotation issue. Components that look perfectly oriented in your layout show up rotated 90 or 180 degrees in the assembly preview.

Why Rotation Discrepancies Occur

This happens because there’s no universal standard for component orientation. KiCad footprints typically place pin 1 at the top-left corner with 0-degree rotation. But different manufacturers load components into tape reels at different orientations, and different assembly houses interpret rotation values differently.

The problem is particularly noticeable with ICs, polarized capacitors, diodes, and LEDs—any component where orientation matters.

Methods to Correct Rotation Issues

There are several approaches to fixing rotation problems:

Method 1: Manual Correction in Spreadsheet

After generating your position file, open it in Excel. Compare each component’s rotation against the assembly preview from your manufacturer. Add or subtract the necessary degrees to correct misaligned components. This is tedious but works for small boards.

Method 2: Using KiCad JLCPCB Tools Plugin

The kicad-jlcpcb-tools plugin by Bouni is excellent for JLCPCB users. Install it from KiCad’s Plugin and Content Manager using this repository URL: https://raw.githubusercontent.com/Bouni/bouni-kicad-repository/main/repository.json

The plugin automatically applies rotation corrections based on a built-in database of common footprints. It also generates BOM and CPL files formatted specifically for JLCPCB.

Method 3: Using KiBot for Automated Correction

KiBot is a command-line tool that automates KiCad output generation. It includes rotation correction filters specifically for JLCPCB and can be configured to apply custom rotations to any footprint pattern. This approach is ideal for production workflows where you’re generating files frequently.

Common Rotation Corrections by Component Type

Based on my experience and various rotation databases, here are typical corrections needed for JLCPCB:

Component Type	Footprint Pattern	Typical Correction
SOT-23 transistors	SOT-23*	+180°
QFN packages	QFN-*	+90° or -90°
USB connectors	USB*	+180°
Chip LEDs	LED_0805*	+180°
Tantalum capacitors	CP_EIA*	+180°
Crystal oscillators	Crystal*	+90°

These vary between manufacturers and even between different parts from the same manufacturer, so always verify in the assembly preview before ordering.

Handling Components on Both Sides of the Board

When your design has components on both the top and bottom layers, you need to consider how KiCad handles the bottom-side coordinate system.

Bottom Layer Coordinate Conventions

KiCad mirrors components when you flip them to the bottom layer. This means a component’s rotation might appear different in the position file than what you see in the layout. Some assembly houses expect mirrored coordinates for the bottom layer, while others (like JLCPCB) do not mirror.

If you generate separate files for front and back, carefully review the bottom-side file. The Y-coordinates might be inverted or the rotations might need adjustment depending on your manufacturer’s expectations.

Verifying Bottom-Side Component Placement

Before submitting for assembly, always check the assembly preview your manufacturer provides. JLCPCB’s online system shows exactly how they’ll place each component. Look specifically at polarized components on the bottom layer—these are most likely to have issues.

If components appear flipped or rotated incorrectly, you can either edit the position file manually or use a plugin/script to apply systematic corrections.

Excluding Components from the Position File

Not every component in your design should appear in the pick-and-place file. Test points, fiducials (when not placed by machine), mounting holes, and connectors that you’ll hand-solder should typically be excluded.

Using KiCad’s Exclude Attributes

In KiCad 8, you can mark footprints to be excluded from position files. Select the component in the PCB layout, open its properties, and look for the “Fabrication Attributes” section. Enable “Exclude from position files” to remove it from generated output.

You can also mark components as “Exclude from BOM” separately, which is useful for fiducials that should appear in position files (for machine calibration) but not in your bill of materials.

Filtering by Component Type

When generating position files, the dialog offers options to include only SMD components or include through-hole components as well. For typical SMT assembly, select SMD-only to keep your file focused on what the machine will actually place.

Working with Assembly Fiducials

Fiducials are small copper targets that help the pick-and-place machine align itself to your board. They’re typically 1mm circular pads placed near the board corners.

Adding Fiducials in KiCad

Add fiducial footprints from the KiCad library—look for “Fiducial” in the footprint search. Place at least two fiducials diagonally across your board, preferably three for better accuracy. They should be on copper layer with no solder mask coverage.

In your position file, fiducials appear as regular components. Most assembly houses use them for alignment but don’t “place” them since they’re just copper features. If your assembly house asks you to exclude fiducials from the position file, use the exclude attribute mentioned above.

Automating Position File Generation

For production workflows or complex projects, manual file generation becomes tedious. Here are tools that automate the process.

KiBot Command-Line Automation

KiBot runs from the command line and can generate all your fabrication outputs automatically. A basic configuration for position files looks like:

yaml

kibot:  version: 1outputs:  – name: ‘position’    type: position    options:      format: CSV      units: millimeters      separate_files_for_front_and_back: false      only_smd: true

Run KiBot against your project, and it generates consistent output every time. You can extend the configuration to include rotation corrections, custom column names, and filtering.

Integration with Version Control

If you’re using Git for your KiCad projects (which you should be), consider adding a pre-commit hook or CI pipeline that generates fabrication files automatically. This ensures your output files always match your current design and eliminates the possibility of submitting outdated position data.

Troubleshooting Common Position File Issues

Here are solutions to problems I’ve encountered repeatedly over the years.

Components Missing from Output

If components aren’t appearing in your position file, check these common causes. The component might be marked as through-hole instead of SMD—verify its fabrication attributes. The component might be on a layer you excluded (top vs. bottom). The footprint might not have proper SMD pad attributes set.

Coordinates Seem Wrong

If coordinates look offset or completely wrong, you probably haven’t set the drill/place origin or haven’t enabled “Use drill/place file origin” in the generation dialog. Reset your origin at the board’s lower-left corner and regenerate.

Rotation Values Don’t Match Layout

This is normal and expected with KiCad. The rotation value represents the component’s orientation relative to its default library orientation, not necessarily what you see visually. Always verify placement using your manufacturer’s preview tool.

Useful Resources and Tools

Here are links to resources that help with KiCad position file generation:

Official KiCad Documentation KiCad 8.0 PCB Editor Documentation: https://docs.kicad.org/8.0/en/pcbnew/pcbnew.html

Plugins and Scripts JLCPCB Tools Plugin: https://github.com/Bouni/kicad-jlcpcb-tools KiBot Automation Tool: https://github.com/INTI-CMNB/KiBot JLC2KiCad Library Generator: https://pypi.org/project/JLC2KiCadLib/

Manufacturer Resources JLCPCB BOM/CPL Guide: https://jlcpcb.com/help/article/How-to-generate-the-BOM-and-Centroid-file-from-KiCAD PCBWay Position File Guide: https://www.pcbway.com/helpcenter/design_instruction/Generate_Position_File_in_Kicad.html

Parts Database JLCPCB/LCSC Parts Database: https://jlcpcb.com/parts

Frequently Asked Questions

What is the difference between a position file and a centroid file in KiCad?

These terms refer to the same thing. KiCad calls it a “Footprint Position File” with the .pos extension, while assembly houses often use terms like centroid file, pick-and-place file, XY data, or component placement list (CPL). They all contain the same information: component coordinates, rotation, and layer assignment needed for automated assembly.

Why do my components show rotated in the JLCPCB assembly preview?

KiCad and JLCPCB use different conventions for component orientation. KiCad’s position file reports rotation based on how the footprint was defined in the library. JLCPCB interprets these values differently for some component types. The solution is to apply rotation corrections—either manually in a spreadsheet, using the kicad-jlcpcb-tools plugin, or with KiBot automation. Always verify placement in JLCPCB’s preview before confirming your order.

Should I generate separate position files for top and bottom layers?

Either approach works for most manufacturers. A single combined file includes a “Side” column indicating which layer each component belongs to. Separate files can be easier to review individually. Check your specific manufacturer’s preference—JLCPCB accepts both formats. If you’re assembling only one side, generate a single file for that side to keep things simple.

How do I add LCSC part numbers to my KiCad position file?

LCSC part numbers aren’t included in the standard position file—they belong in your BOM. In KiCad, add a custom field called “LCSC” to each schematic symbol and enter the part number (like C12345). When generating your BOM, include this field. The position file identifies components by reference designator, while the BOM links designators to specific parts via the LCSC number. Together, these files tell the assembly house exactly what to place and where.

What units should I use for my KiCad position file—millimeters or inches?

Use millimeters. It’s the international standard for PCB manufacturing, and virtually all modern assembly equipment works natively in metric units. Using inches introduces potential conversion errors and can cause confusion with some manufacturers. KiCad defaults to millimeters for position files, so leave this setting unchanged unless your manufacturer explicitly requires inches.

Final Thoughts on KiCad Position File Generation

Getting your pick-and-place file right saves time, money, and frustration. The process in KiCad is straightforward: set your origin at the board corner, generate the position file with correct settings, and verify the output before submitting.

The rotation issue trips up nearly everyone at first. Don’t let it discourage you—once you understand why it happens and have a correction workflow in place, it becomes routine. Plugins like kicad-jlcpcb-tools or automation tools like KiBot make this even easier.

The most important takeaway: always verify your placement in your manufacturer’s preview tool before confirming the order. Five minutes of verification can save days of waiting for corrected boards.

KiCad has matured into a professional-grade tool that handles production workflows as well as any commercial alternative. With the right process for generating and verifying your position files, you can confidently send boards for assembly knowing they’ll come back correctly built.