PyGerber is a collection of tools that simplify working with the Gerber X3 format in
Python. It is based on Ucamco's
The Gerber Layer Format Specification, Revision 2024.05 (available on
Ucamco's website).
PyGerber can be used both as an executable (via a command-line interface) and as a Python library.
PyGerber supports modern features from the latest version of the standard (2024.05). At the same time, it implements many older and removed functionalities for backwards compatibility. This makes it usable with files compliant with X3 as well as with X2, RS-274X, and RS-274D. Because access to files in older standards is limited and those standards contain ambiguities, some legacy behaviors may be incorrect.
If you find a bug in the PyGerber library, please file a bug report using one of the issue templates available on the Create new issue page in the PyGerber repository. We will examine reports and fix issues when possible.
If you have questions or suggestions, please open a discussion in the Discussions section of the repository.
Install PyGerber from PyPI with pip:
pip install pygerber
This installs the core features only. The language server, SVG rendering support, and other optional features are available via extras. To install all extras use:
pip install pygerber[all]
To install the latest development version, use the GitHub repository URL with the git+
prefix:
pip install git+https://github.com/Argmaster/pygerber
PyGerber has online documentation hosted on GitHub Pages. It's a great starting point for using PyGerber: PyGerber documentation. For documentation of older versions, use the version selector next to the title in the top bar.
PyGerber is licensed under the MIT License. The full text is available in the LICENSE file at the root of the repository.
Some testing assets and example files are distributed under different licenses; their
license files are provided alongside the assets. For example, some files from KiCad demo
projects are licensed under CC BY-SA 4.0.
The collection of tools available in PyGerber constantly grows. Some tools are exposed via the API, others include a command-line interface. Below is a list of currently available tools:
- Image renderer (PNG/JPEG/SVG)
[API][CLI] - Code formatter
[API][CLI] - Gerber code generation
[API] - Language server (requires
language_serverextras) (Visual Studio Code extension available)[CLI] - Pygments Gerber syntax lexer plugin (requires
pygmentsextras)[CLI]
PyGerber provides APIs for accessing most of its functionality. The modules listed below are intended for use as stable library APIs; they re-export public parts of the implementation in a convenient way. Avoid importing from modules not listed here or not documented, as those modules are not part of public APIs and may be changed or removed at any time.
Below you can find a list of available APIs:
pygerber.gerber.api(open issue)pygerber.gerber.ast(open issue)pygerber.gerber.ast.nodes(open issue)pygerber.gerber.compiler(open issue)pygerber.gerber.parser(open issue)pygerber.gerber.formatter(open issue)pygerber.builder.gerber(open issue)pygerber.builder.rvmc(open issue)pygerber.vm(open issue)pygerber.vm.commands(open issue)pygerber.vm.types(open issue)pygerber.vm.pillow(open issue)pygerber.vm.shapely(open issue)
If you need a symbol that is not re-exported from these modules (for example, an exception class you need to catch), please open an issue using the corresponding "open issue" link so we can evaluate adding the missing re-export. If the provided template doesn't match your case, fill the fields according to the template guidelines and we will sort it out.
If you have found a bug in a particular part of PyGerber, please use the open issue
link next to the module name above to open an issue submission form. Alternatively,
choose one of the issue templates on the
Create new issue page in the
PyGerber repository and follow the template guidelines to simplify reproducing the issue
for maintainers. If there is no dedicated template, use the
PyGerber Bug Report
template.
PyGerber provides a non-interactive command-line interface to access its tools. The
pygerber command is available after installation and exposes functionality via
subcommands.
To check the installed version, run:
pygerber --versionTo convert a Gerber file to PNG, use the pygerber gerber convert png command. For
example, following command converts source.gbr (a copper layer) to a PNG at 600 DPMM
resolution:
pygerber gerber convert png source.gbr -o output.png -d 600 -s copper_alphaThis creates output.png in the current working directory. Depending on your image size
you may need to adjust -d (--dpmm) to increase or decrease the resolution. Be
careful with the resoultion, as choosing too low value may result in image being empty.
Here is an example result of converting a Gerber file to PNG image:
There are more export target formats available, like JPEG, TIFF, or SVG. Use the
--help flag to list available conversion commands:
pygerber gerber convert --helpFor more detailed command-line documentation, see the Gerber → Command Line section
in the documentation.
PyGerber provides a Gerber X3/X2 Language Server conforming to the
Language Server Protocol. To
enable it, install the language-server extras:
pip install pygerber[language-server]
To check if the language server is available, run the following command:
pygerber is-language-server-available
If you encounter a problem with the language server, please report it using the Issues page of the PyGerber repository.
To fully utilize the language server, use the Visual Studio Code extension
Gerber X3/X2 Format Support
(argmaster.gerber-x3-x2-format-support). The extension repository is available
here. If you encounter
problems with the extension, report them on the extension's Issues page; if the problem
is caused by the language server we will move the report to the PyGerber repository as
needed.
For development guidelines please visit the documentation Development section
here.
I would like to thank Professor Janusz Młodzianowski from the University of Gdańsk, who inspired me with the idea to implement the Gerber format at the beginning of my bachelor's degree. I would also like to express my gratitude to Karel Tavernier, the long-time steward of the Gerber format, for his support and expert guidance during my work on this project. Without them, this project would not have come to life. Finally, I would like to thank all the people who have contributed, are contributing, and will contribute to PyGerber. Your help is invaluable and I am grateful for it.