Install & Compatibility
Where this runs
tested against v2.5.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✕ build_error
py 3.9
✕ build_error
✕ build_error
418MB installed
● package 418MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
kfactory
✓ import kfactory as kf
KCell
✓ import kfactory as kf
c = kf.KCell('my_cell')
layer
✓ import kfactory as kf
LAYER = kf.kcl.layer(1, 0)
✗ import kfactory as kf
LAYER = kf.kcl.Layer(1,0)
The layer API is a function `kf.kcl.layer()`, not a class `kf.kcl.Layer()` or direct access to `kf.Layer` from older versions.
This quickstart demonstrates creating a basic KCell, defining a layer using the `kf.kcl.layer` API, adding a simple rectangle and text, and saving it to a GDSII file. The `c.show()` method is commented out but can be used to launch the KLayout GUI and view the cell directly, assuming KLayout is properly installed and discoverable.
import kfactory as kf
import os
c = kf.KCell('my_first_cell')
# Create a KLayout KCellLayer object for layer (1,0)
# Arguments are (layer_id, datatype_id)
LAYER_1_0 = kf.kcl.layer(1, 0)
# Add a rectangle to the cell on LAYER_1_0
# Coordinates are in nanometers (1000 = 1um, 2000 = 2um)
c.create_rectangle(LAYER_1_0, 1000, 2000)
# You can also add text
c.create_text("Hello KFactory!", LAYER_1_0, 1000)
# Save the cell to a GDSII file
output_gds_path = os.path.join(os.getcwd(), 'my_first_cell.gds')
c.write(output_gds_path)
print(f"GDSII file saved to: {output_gds_path}")
# To visualize, KFactory can launch KLayout if installed and configured
# Uncomment the line below to open the cell in KLayout GUI
# c.show()
Debug
Known issues
gotchaKFactory requires Python 3.11 or newer. Attempting to install or run with older Python versions will result in installation failures or runtime errors.fixEnsure your Python environment is 3.11 or newer. Consider using `pyenv` or virtual environments to manage Python versions.
affects: All versions from 2.0 onwards (PyPI `requires_python: >=3.11`)
gotchaKFactory is a wrapper around KLayout's native Python API (`pya`). You must have KLayout (the full GUI application) installed on your system, and its `pya` module needs to be discoverable by your Python environment (e.g., via `PYTHONPATH`). Without KLayout and `pya`, KFactory cannot function, leading to `ModuleNotFoundError` for `pya`.fixInstall KLayout from the official website. Ensure the directory containing KLayout's `pya` module (e.g., `C:\KLayout\klayout-0.x.x\bin` on Windows or `~/KLayout/klayout-0.x.x/lib/python/site-packages` on Linux/macOS, depending on KLayout installation method) is added to your `PYTHONPATH` environment variable. Alternatively, execute your KFactory script directly through KLayout's integrated Python environment using `klayout -r myscript.py`.
affects: All
deprecatedThe API for defining layers has evolved. Older patterns like direct access to `kf.Layer` or `kf.kcell.Layer` (or attempting to instantiate them as classes) are deprecated or no longer function as expected. The correct and current method is to use the `kf.kcl.layer()` function.fixAlways use `kf.kcl.layer(layer_id, datatype_id)` to create KFactory layer objects. For example, `LAYER_1_0 = kf.kcl.layer(1, 0)`.
affects: Potentially from 1.x to 2.x, or older 2.x releases.
Errors
Common errors & fixes
ERROR: Package 'kfactory' requires Python '>=3.11' but the currently active Python environment is '3.x'
Attempting to install `kfactory` in a Python environment older than 3.11.
fixUpgrade your Python environment to 3.11 or newer, or create a new virtual environment with a compatible Python version (e.g., `python3.11 -m venv .venv`).
ModuleNotFoundError: No module named 'pya'
The KLayout Python API (`pya`) is not found by your Python interpreter. This typically means KLayout is not installed, or its `pya` module's location is not included in your `PYTHONPATH`.
fixInstall KLayout (the full GUI application, not just `klayout-python`). Then, either ensure KLayout's `pya` module directory is added to your `PYTHONPATH` environment variable, or run your Python script using KLayout's integrated Python environment (e.g., `klayout -r myscript.py`). Consult KLayout documentation for `pya` setup.
AttributeError: module 'kfactory.kcell' has no attribute 'Layer'
Attempting to access an older or non-existent layer API, such as `kf.kcl.Layer`. The current API for defining layers is a function, `kf.kcl.layer()`.
fixUse the `kf.kcl.layer(layer_id, datatype_id)` function to create KFactory layer objects. For instance, `my_layer = kf.kcl.layer(1, 0)`.
Upgrade
Version history
2.5.3latest on PyPI · released May 21, 2026
Audit
Dependencies
No dependency data recorded yet.