jBOM — KiCad Bill of Materials and Placement Generator

Why jBOM?

Designing a PCB in KiCad is only part of the journey that results in a fabricated and assembled electronic product. PCB fabrication requires Gerber files; assembly requires a Bill of Materials (BOM) and a Placement file (CPL/POS). jBOM generates all three.

The common KiCad workflow has you annotate your KiCad symbols with supply chain details such as "IPN:RES-331-0603", "MFG:Yageo", "MPN:CC0603KRX7R9BB104", "LCSC:C123456", and then use KiCad's fabrication plugins to generate BOM and CPL files. This mechanism is easy to understand, and, through KiCad's web/database library integration, plugins such as Part-DB, InvenTree, PartsBox and GitPLM connect to extensive parts databases. While these this workflow has proven sufficient for many developers, it inadvertently makes it difficult to decouple supply chain evolution from a project's electronic and mechanical specifications.

jBOM solves this by separating part selection from circuit design. You design with generic values ("10k, 5%, Resistor_SMD:R_0603_1608Metric"), maintain a currated inventory file with your desired parts, and jBOM intelligently matches them at BOM generation time. Changing suppliers or cost reducing a set of projects is as simple as updating an inventory spreadsheet.

Documentation

Command line: docs/README.man1.md Python Library API: docs/README.man3.md KiCad Eeschema Integration: docs/README.man4.md jBOM Inventory File Format: docs/README.man5.md

Installation

Requires Python 3.10 or newer.

From PyPI (recommended):

# Basic installation (with only CSV inventory support)
pip install jbom

# With CSV, Excel and Numbers spreadsheet support
pip install jbom[all]

# With CSV and Excel support
pip install jbom[excel]
# With CSV and Apple Numbers support
pip install jbom[numbers]

# With Mouser Search support
pip install jbom[search]

Quick Start

Scenario: New KiCad project → JLCPCB manufacturing files.

1. Extract an inventory template

jbom inventory MyProject/ -o inventory.csv

This writes one row per unique Value + Package combination found in your schematics. IPN, Category, Value, and Package are pre-filled; supplier columns (LCSC, Manufacturer, MFGPN) are blank for you to complete.

2. Audit schematic field quality

Before filling in part numbers, verify your schematic fields are complete:

jbom audit MyProject/ -o report.csv

This checks every component against jBOM's field taxonomy and writes findings to report.csv. Open it in a spreadsheet, fill in ApprovedValue for any QUALITY_ISSUE rows, set Action to SET, then apply the fixes back to your schematic:

jbom annotate MyProject/ --repairs report.csv

Once the schematic is clean, verify your inventory covers every component:

jbom audit MyProject/ --inventory inventory.csv

3. Fill in part numbers for JLC's LCSC supplier

An inventory file maps your generic schematic values to real parts from a supplier's catalog — in this case LCSC, which JLCPCB uses for sourcing. Open inventory.csv and fill in the LCSC column for each part you want JLCPCB to source. Set Priority to 1 on rows you want matched first.

To find LCSC part numbers:

  • Search interactively: jbom search "10k 0603 resistor" --supplier lcsc
  • Look up manually at jlcpcb.com/parts
  • Export your JLCPCB private parts library (User Center → My Inventory → My Parts Lib → Export) and load it alongside: --inventory project.csv --inventory jlc_library.xlsx

Coming soon: jbom inventory MyProject/ --supplier lcsc --limit 3 -o inventory.csv will search and populate part numbers automatically.

4. Generate fabrication files

Use jbom fab for a one-shot run that writes everything to a production/ folder:

jbom fab MyProject/ --jlc --inventory inventory.csv

This produces:

production/
  jbom.csv                    ← BOM for JLCPCB
  cpl.csv                     ← component placement
  MyProject_1.0.zip           ← Gerber archive for upload (requires kicad-cli)
  backups/MyProject_1.0_....zip

Or generate files individually:

jbom bom MyProject/ --jlc --inventory inventory.csv   # writes MyProject.bom.csv
jbom pos MyProject/ --jlc                             # writes MyProject.pos.csv
jbom gerbers MyProject/ --jlc                         # writes gerbers/ (requires kicad-cli)

Preview without writing: jbom bom MyProject/ --jlc --inventory inventory.csv -o console

For the full step-by-step walkthrough, options, and troubleshooting tips, see the Tutorial series.

KiCad Integration

jBOM provides a Pcbnew ActionPlugin (a toolbar button in the PCB editor) that generates BOM, pick-and-place (CPL), and Gerbers in one click. The plugin is distributed through KiCad's Plugin and Content Manager (PCM) as a separate channel from PyPI; pip install jbom installs the CLI and library only and does not register the KiCad plugin.

To install the plugin:

  1. Download the latest PCM archive from GitHub's stable-name URL: https://github.com/plocher/jBOM/releases/latest/download/jbom-pcm.zip (GitHub redirects releases/latest/download/<asset> to whatever asset of that name is attached to the newest release, so the URL never needs to be edited when a new version ships.)
  2. In KiCad, open Plugin and Content Manager, choose Install from File…, and select the downloaded jbom-pcm.zip.
  3. Open the PCB Editor (Pcbnew); the jBOM toolbar button appears automatically. Vendored runtime dependencies ship inside the archive, so no additional pip install step is required inside KiCad's bundled Python.

For fabricator flags, output columns, inventory requirements, custom fabricator configuration, and troubleshooting, see docs/reference/kicad-plugin.md.

Legacy Eeschema BOM wrapper. The repo also ships kicad_jbom_plugin.py, a thin shim that lets Eeschema's Tools → Generate BOM dialog call jbom bom for schematic-only BOM output. This path is optional and requires a one-time manual registration via Eeschema's Add-plugin dialog. See the kicad-plugin-setup skill if you need it. Most users should use the PCM ActionPlugin above instead.

Configuration

Built-in fabricator profiles: --jlc, --pcbway, --seeed.

To create a custom profile or configure organisation-wide defaults, see docs/tutorial/README.documentation.md and docs/README.configuration.md.

Contributing

Contributions are welcome! jBOM is developed on GitHub at github.com/plocher/jBOM.

To contribute:

  1. Fork the repository
  2. Create a feature branch
  3. Run tests locally:
    • Fast canary: PYTHONPATH=src python -m pytest tests/unit/test_cli_help.py tests/unit/test_unified_loader.py tests/unit/test_fabricator_config_schema.py tests/unit/test_supplier_config_schema.py -q and PYTHONPATH=src python -m behave --format progress features/cli/basics.feature features/project/file.feature features/bom/core.feature features/pos/core.feature features/inventory/core.feature features/audit/core.feature
    • Comprehensive: PYTHONPATH=src python -m pytest tests/ -v and PYTHONPATH=src python -m behave --format progress features/
  4. Submit a pull request

Regenerate deterministic search parity artifacts (fixture-based): python scripts/generate_search_parity_artifacts.py

Regenerate baseline-vs-candidate parity delta evidence: python scripts/generate_search_parity_delta_report.py

See docs/CONTRIBUTING.md for details.

License: MIT — See LICENSE file for full terms. Author: John Plocher

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (7.9.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for plocher from gravatar.com plocher

Credits

Author: John Plocher

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

excel numbers search dev all

Tags

kicad bom bill-of-materials pcb electronics inventory

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jbom-7.5.0.tar.gz (726.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

jbom-7.5.0-py3-none-any.whl (396.4 kB view details)

Uploaded Python 3

File details

Details for the file jbom-7.5.0.tar.gz.

File metadata

  • Download URL: jbom-7.5.0.tar.gz
  • Upload date:
  • Size: 726.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.10.20

File hashes

Hashes for jbom-7.5.0.tar.gz
Algorithm Hash digest
SHA256 c76620311ae7f4f3078705432af968aa0680ffeb2b201bc1c237b0868363b052
MD5 bdcecf4f51c3b2083842090df5bc2837
BLAKE2b-256 da9017b0a87130f56ab19c4e0ec881467331077fee76a6d3f8f85eac24461f26

See more details on using hashes here.

File details

Details for the file jbom-7.5.0-py3-none-any.whl.

File metadata

  • Download URL: jbom-7.5.0-py3-none-any.whl
  • Upload date:
  • Size: 396.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.10.20

File hashes

Hashes for jbom-7.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 02b09870d26e83d00deb18de4f9a669e5ddfd5ede6b26ec8fc49e76aa1e109d4
MD5 c56f28edbff8f7aab4b3bd482999625a
BLAKE2b-256 c7c9a9c3de098d9e07d457a0181d4a0b82eddf0e9527b4d4b773dc757f71e111

See more details on using hashes here.

Release history Release notifications | RSS feed

7.9.1

2 files

7.9.0

2 files

7.8.2

2 files

7.8.1

2 files

7.8.0

2 files

7.7.0

2 files

7.6.0

2 files

This release

7.5.0 This release

2 files

7.4.0

2 files

7.3.4

2 files

7.3.3

2 files

7.3.2

2 files

7.3.1

2 files

7.3.0

2 files

7.2.0

2 files

7.1.0

2 files

7.0.2

2 files

7.0.1

2 files

7.0.0

2 files

6.60.0

2 files

6.59.0

2 files

6.58.1

2 files

6.58.0

2 files

6.57.0

2 files

6.56.0

2 files

6.55.2

2 files

6.55.1

2 files

6.55.0

2 files

6.54.0

2 files

6.53.0

2 files

6.52.2

2 files

6.52.1

2 files

6.52.0

2 files

6.51.5

2 files

6.51.4

2 files

6.51.3

2 files

6.51.2

2 files

6.51.1

2 files

6.51.0

2 files

6.50.3

2 files

6.50.2

2 files

6.50.1

2 files

6.50.0

2 files

6.49.0

2 files

6.48.1

2 files

6.48.0

2 files

6.47.0

2 files

6.46.0

2 files

6.45.0

2 files

6.44.2

2 files

6.44.1

2 files

6.44.0

2 files

6.43.0

2 files

6.42.0

2 files

6.41.2

2 files

6.41.1

2 files

6.41.0

2 files

6.40.0

2 files

6.39.6

2 files

6.39.5

2 files

6.39.4

2 files

6.39.3

2 files

6.39.2

2 files

6.39.1

2 files

6.39.0

2 files

6.38.1

2 files

6.38.0

2 files

6.37.0

2 files

6.36.1

2 files

6.36.0

2 files

6.35.0

2 files

6.34.1

2 files

6.34.0

2 files

6.33.0

2 files

6.32.0

2 files

6.31.0

2 files

6.30.2

2 files

6.30.1

2 files

6.30.0

2 files

6.29.0

2 files

6.28.1

2 files

6.28.0

2 files

6.27.2

2 files

6.27.1

2 files

6.27.0

2 files

6.26.0

2 files

6.25.0

2 files

6.24.0

2 files

6.23.0

2 files

6.22.0

2 files

6.21.0

2 files

6.20.0

2 files

6.19.1

2 files

6.19.0

2 files

6.18.1

2 files

6.18.0

2 files

6.17.0

2 files

6.16.0

2 files

6.15.0

2 files

6.14.0

2 files

6.13.0

2 files

6.12.0

2 files

6.11.0

2 files

6.10.0

2 files

6.9.2

2 files

6.9.1

2 files

6.9.0

2 files

6.8.0

2 files

6.7.2

2 files

6.7.1

2 files

6.7.0

2 files

6.6.0

2 files

6.5.0

2 files

6.4.0

2 files

6.3.1

2 files

6.3.0

2 files

6.2.0

2 files

6.1.0

2 files

6.0.0

2 files

5.0.0

2 files

4.12.0

2 files

4.11.0

2 files

4.10.1

2 files

4.10.0

2 files

4.9.0

2 files

4.8.0

2 files

4.7.0

2 files

4.6.0

2 files

4.5.1

2 files

4.5.0

2 files

4.4.0

2 files

4.3.0

2 files

4.2.1

2 files

4.2.0

2 files

4.1.0

2 files

4.0.0

2 files

3.6.0

2 files

3.5.0

2 files

3.4.0

2 files

3.3.1

2 files

3.3.0

2 files

3.2.0

2 files

3.1.0

2 files

3.0.0

2 files

2.1.5

2 files

2.1.4

2 files

2.1.0

2 files

1.0.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page