# kicad-jlcpcb-tools: from KiCad board to JLCPCB fabrication and assembly files

> kicad-jlcpcb-tools is a KiCad PCB Editor plugin that generates the Gerber, Excellon, BOM and CPL files JLCPCB needs for fabrication and assembly, while letting designers assign LCSC part numbers directly from a built-in parts browser. KiCad 10 adds a variant table for comparing and exporting multiple build configurations.

**Bouni/kicad-jlcpcb-tools** — Plugin to generate BOM + CPL files for JLCPCB, assigning LCSC part numbers directly from the plugin, query the JLCPCB parts database, lookup datasheets and much more.

- Repository: https://github.com/Bouni/kicad-jlcpcb-tools
- Stars: 2,104 · Forks: 178
- Language: Python
- License: MIT
- Published: 2026-10-09 · Updated: 2026-10-09 · Language: en
- Canonical page: https://hysenlabs.com/projects/bouni-kicad-jlcpcb-tools

## The gap between KiCad board layout and a JLCPCB assembly order

KiCad produces a finished PCB layout, but sending a board to JLCPCB for assembly requires more than a Gerber archive. JLCPCB's assembly service depends on a bill of materials with LCSC part numbers assigned to each component and a component placement list with exact positions, orientations and which side of the board each part lands on. Preparing those two files by hand, while keeping LCSC numbers consistent with what JLCPCB actually stocks, is the step that kicad-jlcpcb-tools removes.

The plugin adds an entry under Tools, External Plugins in the KiCad PCB Editor and generates all four output types from one place: Gerber files, Excellon drill files, a BOM file and a CPL file. It also gives designers a parts browser that queries JLCPCB's parts database and writes the chosen LCSC number directly into the footprint's properties in the board file. Once assigned there, the number travels with the project and appears automatically in the next BOM export.

The intended users are hardware designers who use JLCPCB for assembled boards and want the LCSC assignment and fabrication file steps handled inside KiCad rather than in a separate spreadsheet. Teams relying on other assembly houses, or on component suppliers that do not use LCSC part numbers, will not benefit from the database search.

## How the four output files fit JLCPCB's upload workflow

The four output types divide the fabrication and assembly job at its natural seams. Gerber layers cover copper, solder mask, silkscreen and board outline. Excellon handles drill positions. A BOM ties component references to LCSC part numbers, and a CPL carries the placement position, rotation and board side that pick-and-place machines consume.

KiCad's own export dialogs can produce most of those separately, but without the LCSC assignment step they are incomplete for JLCPCB assembly. The plugin ties them together: LCSC numbers from the database search land in the BOM automatically, and placement corrections for components whose footprint orientation differs from what an assigned part expects are tracked in the plugin's corrections system. CORRECTIONS.md at the repository root documents that system, and correction_data.py is the corresponding source file.

The corrections address an assembly problem: a footprint placed at one angle in the board editor can correspond to a physical part whose pin-one mark sits at a different angle. Two rule types cover this: a part-specific rule reads from the LCSC record for that exact component, while a pattern rule reads orientation data from the Default variant's reference, Value and placed footprint. Swapping an LCSC assignment pulls in the new part's rule without requiring a manual correction update.

## Parts database search, LCSC assignment and datasheet access

The parts browser is what separates kicad-jlcpcb-tools from a plain Gerber export script. A search dialog inside the plugin connects to JLCPCB's parts database, retrieves matching components, and shows them with stock and pricing indicators. Selecting a result writes the LCSC number into the KiCad footprint. Because that number lives in the board file rather than a separate spreadsheet, every collaborator who opens the project sees the same assignments, and the BOM reflects them without a manual reconciliation step.

The repository layout shows the data flow: lcsc.py, lcsc_api.py and lcsc_entry_dialog.py handle the lookup path, while part_assignments.py and part_preferences.py manage how assignments are stored and retrieved. A local copy of the JLCPCB parts catalog is maintained by a GitHub Actions workflow at update_parts_database.yml in the repository, which keeps the database current on a schedule.

Datasheet access is a distinct feature the README lists alongside the database search: selecting a component in the parts browser exposes a link to its datasheet URL. There is no annotation export, no pin mapping between an LCSC datasheet and a KiCad symbol, and no version tracking across LCSC part revisions. For parts that JLCPCB does not stock, the plugin provides no alternative datasheet path.

## Flatpak KiCad omits pip and requests, requiring three commands before the plugin loads

Two routes get the plugin installed. The first is KiCad's Plugin and Content Manager: add the URL below as a custom repository in the PCM and install from there.

```sh
https://raw.githubusercontent.com/Bouni/bouni-kicad-repository/main/repository.json
```

The second is a git clone into the KiCad plugins folder. On Linux the target path is:

```sh
cd ~/.local/share/kicad/<version>/scripting/plugins
git clone https://github.com/Bouni/kicad-jlcpcb-tools.git
```

On Windows with Command Prompt:

```cmd
cd "%USERPROFILE%\Documents\KiCad\<version>\scripting\plugins"
git clone https://github.com/Bouni/kicad-jlcpcb-tools.git
```

On macOS the folder is `~/Documents/KiCad/<version>/scripting/plugins`. The `<version>` placeholder is 7.0, 8.0, 9.0 or X.YY; the README notes that scripting/plugins may need to be created first. After cloning, choosing Tools, External Plugins, Refresh Plugins in the PCB Editor loads the code without a full restart.

The Flatpak build of KiCad ships without pip or requests, and requests is a direct dependency of the plugin. Three commands fix the gap:

```sh
flatpak run --command=sh org.kicad.KiCad
python -m ensurepip --upgrade
/var/data/python/bin/pip3 install requests
```

Issue #94 in the project tracker covers that workaround in more detail. Without those steps, the Flatpak environment will not have the library the plugin needs.

## Design variants in KiCad 10: comparing and exporting multiple board configurations

KiCad 10 introduced named design variants, and kicad-jlcpcb-tools added a variant table to match. When a board carries named variants, the plugin replaces the ordinary parts table with a side-by-side view of all configurations. Boards without named variants keep the original interface and are unaffected by this feature.

In the variant table, each component row spans all variants. Value, LCSC assignment and the BOM, POS and POP (populated) flags are editable independently per variant. Cells that differ from Default are highlighted in yellow, and a yellow outline appears around the affected variant's cells in that row. A Differences only checkbox in the toolbar hides rows where all variants agree, focusing the view on components that actually change between builds.

Copy and paste work between variants. Selecting components in one variant and pasting into another transfers Value, LCSC and BOM/POS/POP settings for every selected component. For a single value, Copy cell value handles it; for a group of fields across multiple target variants, Copy to variants allows choosing fields and destination variants in one step. Variant headers are draggable to reorder them for side-by-side comparison.

Generating fabrication output requires picking one variant as the Output variant; only that configuration's component set, populated flags and LCSC assignments flow into the resulting files. Stock availability for each variant's assigned parts appears in the same table view, so a substitution that puts a component out of stock shows up before file generation rather than after. All variant data sits inside the .kicad_pcb file, so a project export carries the configurations without extra sidecar files.

## The plugin operates in the PCB Editor only and targets JLCPCB exclusively

kicad-jlcpcb-tools runs inside the KiCad PCB Editor, not the schematic editor. That boundary means LCSC numbers and BOM/POS/POP flags live in the board file rather than in schematic symbols. A workflow that stores component data in the schematic must transfer it to the board before the plugin can work with it. The README and the repository file list show no automated bridge between schematic symbol properties and board footprint properties.

Datasheet lookup is limited to parts that exist in the JLCPCB parts database. For custom components, parts sourced from other distributors, or anything JLCPCB does not stock, the plugin provides no datasheet access and no alternative lookup path.

The BOM and CPL formats the plugin produces are matched to JLCPCB's upload interface. Anyone ordering from a different assembly house will need to use KiCad's own export dialogs instead, because the plugin offers no format configuration for other services. This is the right tool only when JLCPCB is the assembly house, and the scope is intentional rather than an oversight.

## MIT license, Python 3.10 floor, and the last push on 2026-10-04

The project is distributed under the MIT license. pyproject.toml sets requires-python = ">=3.10" and lists eight runtime dependencies: click>=8.0, humanize>=4.0, requests>=2.28, cachetools>=5.0, ratelimit>=2.2.1, tqdm>=4.0, retry>=0.9.2 and split_file_reader>=0.1.4. The classifier list covers Python 3.10, 3.11 and 3.12.

The latest tagged release is 2026.04.03, published on 2026-04-23. Three releases arrived in April 2026: 2026.04.01 on 2026-04-13, 2026.04.02 on 2026-04-14 and 2026.04.03 on 2026-04-23. The last push to the repository was on 2026-10-04, and the repository is not archived.

Development dependencies are listed under the dev optional extras in pyproject.toml: pytest>=7.0, pytest-cov>=4.0 and ruff>=0.1.0. The repository includes conftest.py at the root, which supports the test setup. The project carries a Hacktoberfest topic tag, indicating it accepts external contributions during that period. KiCad v7, v8, v9 and v10 are all listed as supported versions in the README; v6 does not appear in the badge row, and confirming your installed version against that list before adopting the plugin avoids a compatibility surprise.

## Conclusion

Use kicad-jlcpcb-tools if you design PCBs in KiCad v7, v8, v9 or v10 and send them to JLCPCB for assembly. The parts database search removes the work of manually tracking LCSC numbers, and the variant table in KiCad 10 handles multi-configuration builds in one place. Skip it if your assembly house is not JLCPCB, because the file formats are tuned for that service and offer no configuration for others. Before starting, confirm the Python environment inside your KiCad plugins folder satisfies requests>=2.28. Flatpak users need the three-step workaround documented in issue #94 before the plugin will load.

## FAQ

### How do I install kicad-jlcpcb-tools in KiCad?

The recommended method is KiCad's Plugin and Content Manager. Add the URL https://raw.githubusercontent.com/Bouni/bouni-kicad-repository/main/repository.json as a custom repository and install from there. A git clone into the KiCad scripting/plugins folder is the alternative for users who prefer manual control over updates.

### Which KiCad versions does kicad-jlcpcb-tools support?

The README lists KiCad v7, v8, v9 and v10 as supported versions. Design variant features, which allow comparing and exporting multiple board configurations side by side, require KiCad 10 specifically.

### What is an LCSC part number and why does kicad-jlcpcb-tools need it?

LCSC is JLCPCB's component supply division. Assigning an LCSC number to a KiCad footprint tells JLCPCB's assembly service which component to place. The plugin searches the JLCPCB parts database and writes the selected number directly into the board file, where it stays for all future BOM exports.

### Does kicad-jlcpcb-tools work with the Flatpak version of KiCad?

The Flatpak build does not include pip or the requests library, which the plugin requires. The README documents three commands to install the missing dependency and references issue #94 for further detail on that workaround.

### Can kicad-jlcpcb-tools generate files for PCB manufacturers other than JLCPCB?

The plugin generates BOM and CPL files in formats matched to JLCPCB's upload interface. The README and repository describe no configuration for other services, so users ordering from a different manufacturer need to export those files through KiCad's own export dialogs.

## Sources

- [Bouni/kicad-jlcpcb-tools on GitHub](https://github.com/Bouni/kicad-jlcpcb-tools)
- [Issues](https://github.com/Bouni/kicad-jlcpcb-tools/issues)
- [License: MIT](https://github.com/Bouni/kicad-jlcpcb-tools/blob/main/LICENSE)
- [README](https://github.com/Bouni/kicad-jlcpcb-tools/blob/main/README.md)
- [Releases](https://github.com/Bouni/kicad-jlcpcb-tools/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bouni-kicad-jlcpcb-tools