{"id":8259,"library":"klayout","title":"KLayout Python Module","description":"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.","status":"active","version":"0.30.7","language":"en","source_language":"en","source_url":"https://github.com/klayout/klayout","tags":["EDA","chip design","layout","GDSII","OASIS","scripting","microelectronics"],"install":[{"cmd":"pip install klayout","lang":"bash","label":"Install KLayout Python module"}],"dependencies":[],"imports":[{"note":"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`.","wrong":"import pya","symbol":"db","correct":"import klayout.db as db"},{"note":"The `Layout` class is part of the `klayout.db` module.","symbol":"Layout","correct":"layout = db.Layout()"},{"note":"The `LayerInfo` class for defining layers is part of the `klayout.db` module.","symbol":"LayerInfo","correct":"layer_info = db.LayerInfo(1, 0)"}],"quickstart":{"code":"import klayout.db as db\n\n# Create a new layout object\nlayout = db.Layout()\n\n# Set the database unit (DBU) to 1 nanometer (0.001 micrometers)\nlayout.dbu = 0.001\n\n# Create a top cell named 'TOP'\ntop_cell = layout.create_cell(\"TOP\")\n\n# Define a layer (e.g., GDS layer 1, datatype 0)\nlayer_info = db.LayerInfo(1, 0)\nlayer_idx = layout.layer(layer_info)\n\n# Add a box to the layer in the top cell\n# Coordinates are in micrometers if DBU is 0.001 (e.g., 100x200 um)\nbox = db.DBox(0, 0, 100, 200)\ntop_cell.shapes(layer_idx).insert(box)\n\n# Save the layout to a GDSII file\noutput_filename = \"my_first_layout.gds\"\nlayout.write(output_filename)\n\nprint(f\"Layout '{output_filename}' created successfully.\")","lang":"python","description":"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."},"warnings":[{"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()`).","message":"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.","severity":"breaking","affected_versions":">=0.30.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install klayout` to install the package.","cause":"The `klayout` Python package has not been installed in your current environment.","error":"ModuleNotFoundError: No module named 'klayout'"},{"fix":"Change your import and object instantiation to use `klayout.db`: `import klayout.db as db; layout = db.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.","error":"AttributeError: module 'pya' has no attribute 'Layout'"},{"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.","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.","error":"RuntimeError: Layer 1/0 already exists in layout"}]}