KLayout Python Module

0.30.7 · active · verified Thu Apr 16

KLayout is a layout viewer and editor primarily for integrated circuit layouts (GDSII, OASIS). The `klayout` Python package (v0.30.7) provides a standalone scripting interface to KLayout's powerful database and geometry manipulation functionalities, allowing users to programmatically create, modify, and analyze layouts without requiring the full graphical application. It maintains an active release cadence, with minor updates released frequently to address issues and enhance features, often multiple times a month.

Common errors

```
ModuleNotFoundError: No module named 'klayout'
```
cause The `klayout` Python package has not been installed in your current environment.

fix Run `pip install klayout` to install the package.
```
AttributeError: module 'pya' has no attribute 'Layout'
```
cause You are trying to use classes from `pya` (e.g., `pya.Layout()`) but are running a `klayout` Python package installation (not the full KLayout application environment) where `pya` might not be exposed directly or the new `klayout.db` interface is expected.

fix Change your import and object instantiation to use `klayout.db`: `import klayout.db as db; layout = db.Layout()`.
```
RuntimeError: Layer 1/0 already exists in layout
```
cause You are attempting to define or add the same layer information (e.g., `LayerInfo(1, 0)`) multiple times to the same `Layout` object, which is not allowed. `layout.layer()` will return the index of an *existing* layer if it matches the `LayerInfo` provided.

fix Before creating a new layer index, check if the layer already exists using `layout.find_layer()` or ensure you only call `layout.layer(LayerInfo(...))` once for each unique layer definition. `layout.layer()` is idempotent for existing layer infos.

Warnings

breaking The recommended way to access KLayout's database objects transitioned from `pya` to `klayout.db` starting with KLayout v0.30.0. While `pya` might still be available for compatibility, `klayout.db` offers a more consistent and future-proof interface.
Fix: Migrate your code to use `import klayout.db as db` and access classes/functions through the `db` alias (e.g., `db.Layout()`, `db.DBox()`).
gotcha The `klayout` Python package (installed via `pip`) provides only the scripting interface. It does NOT include the full KLayout graphical user interface (GUI) application. For the GUI, you must download and install the KLayout application separately from the official website.
Fix: Understand that `pip install klayout` is for scripting-only. If you need the GUI, download the appropriate KLayout installer for your operating system from `klayout.de/build.html`.
gotcha KLayout operates with a 'database unit' (DBU) which determines the internal resolution. All coordinates and dimensions are implicitly in DBU units. If not explicitly set, the default DBU can lead to unexpected scaling.
Fix: Always explicitly set `layout.dbu` at the beginning of your script to ensure consistent units (e.g., `layout.dbu = 0.001` for 1nm resolution, meaning coordinates are in micrometers). All input values to geometry functions should then be scaled appropriately to this DBU.

Install

pip install klayout Install KLayout Python module

Imports

db
wrong:
```
import pya
```
correct:
```
import klayout.db as db
```
For Python scripting, `klayout.db` is the recommended and modern way to access the layout database. `pya` is a legacy module, primarily for backward compatibility within the KLayout application's own interpreter, and may not be reliably available or updated with `pip install klayout`.
Layout
```
layout = db.Layout()
```
The `Layout` class is part of the `klayout.db` module.
LayerInfo
```
layer_info = db.LayerInfo(1, 0)
```
The `LayerInfo` class for defining layers is part of the `klayout.db` module.

Quickstart

This quickstart demonstrates how to create a new GDSII layout, define a cell and layer, add a simple rectangular shape, and save the result using the `klayout.db` module.

import klayout.db as db

# Create a new layout object
layout = db.Layout()

# Set the database unit (DBU) to 1 nanometer (0.001 micrometers)
layout.dbu = 0.001

# Create a top cell named 'TOP'
top_cell = layout.create_cell("TOP")

# Define a layer (e.g., GDS layer 1, datatype 0)
layer_info = db.LayerInfo(1, 0)
layer_idx = layout.layer(layer_info)

# Add a box to the layer in the top cell
# Coordinates are in micrometers if DBU is 0.001 (e.g., 100x200 um)
box = db.DBox(0, 0, 100, 200)
top_cell.shapes(layer_idx).insert(box)

# Save the layout to a GDSII file
output_filename = "my_first_layout.gds"
layout.write(output_filename)

print(f"Layout '{output_filename}' created successfully.")

view raw JSON →