We support Python 3.10, 3.11 and 3.12, and recommend VSCode IDE. If you do not have Python installed, you can download Anaconda.

Upon Python installation, open Anaconda Prompt as Administrator and install the latest gdsfactory

anaconda prompt

You can install the latest released gdsfactory using the following command:

pip install gdsfactory --upgrade

If you want to install the latest pre-released version you can run:

pip install git+ --force-reinstall

Please note that some PDKs may only work for a specific version of gdsfactory. Ensure you install the correct gdsfactory version specified in the pyproject.toml file. This will automatically happen when you install gdsfactory as one of the PDK dependencies. For example, pip install gf180 will install the latest gdsfactory version tested for the GlobalFoundries180 PDK.

To determine your python and gdsfactory versions, use the following code:

import sys

import gdsfactory as gf


You can download the jupyter notebooks tutorial and open them with VSCode.

We recommend running the tutorials with VSCode but you can also install and run them with jupyterlab.

pip install jupyterlab

Installation for contributors#

As a contributor, if you are on windows you need to download Git and optionally GitHub Desktop.

Then you need to fork the GitHub repository, git clone it (download it), git add, git commit, git push your improvement. Then pull request your changes to the main branch from the GitHub website.

The following lines will:

  • clone your gdsfactory fork (make sure you change YourUserName with your GitHub user name)

  • download the GDS reference files for running GDS regressions from a separate repo

  • install gdsfactory on your computer in -e edit mode.

  • install pre-commit hooks for making sure your code syntax and style matches some basic rules.

git clone
cd gdsfactory
git clone -b test_klayout test-data-gds
pip install -e .[dev]
pre-commit install


  • Follow Google Python Style Guide and existing code.

  • Make sure tests pass on GitHub.

  • Install pre-commit to get the pre-commit checks passing (autoformat the code, run linter …).

Pre-commit makes sure your code is formatted following black and checks syntax. If you forgot to pre-commit install you can fix pre-commit issues by running

pre-commit run --all-files

until you fix all the issues that the pre-commit check complaints about.


gdsfactory tests are written with pytest. You can run them, from the root of the repository with pytest:

pytest -s

pytest will test any function that starts with test_. You can assert the number of polygons, the name, the length of a route or whatever you want.

In addition to unit tests run against the library, gdsfactory has a suite of regression tests which ensure that Components are never unintentionally modified between revisions. These regression tests include

Test Type







Tests that GDS files have not changed either structurally (cell names and hierarchy) or geometrically (XOR).




Tests that component settings have not changed.




Tests that extracted netlist yaml contents have not changed.




Tests that port locations have not changed




Tests that container settings have not changed

  • regressions tests: avoids unwanted regressions by storing Components port locations in CSV and metadata in YAML files. You can force to regenerate the reference files running pytest --force-regen -s from the repo root directory.

    • tests/components/ stores all the component settings in YAML

    • tests/components/ stores all port locations in a CSV file

    • tests/ stores all the component netlist in YAML and rebuilds the component from the netlist. Converts the routed PIC into YAML and build back into the same PIC from its YAML definition

    • difftest: writes all components GDS in run_layouts and compares them with ref_layouts. When running the test it will do a boolean of the run_layout and the ref_layout and raise an error for any significant differences. It will prompt you to review the differences in klayout and approve or reject the new GDS.

To regenerate regression reference files, you can run

pytest --force-regen -s

Note that the --force-regen flag will regenerate textual reference files, via pytest-regressions. When GDS file regressions are found, the -s flag will cause pytest to step through the failures one-by-one, so you can inspect the XOR result in Klayout (automatically loaded via klive) and debug messages in the terminal. You will be prompted if you would like to accept or reject the set of changes for each file.

Build your own Reticles/projects/PDKs#

We recommend creating a separate python project for each mask and PDK.

pip install cookiecutter
cookiecutter gh:joamatab/python

Make sure you pin the version of gdsfactory that you are using in your pyproject.toml

Test own Reticles/projects/PDKs#

You can take a look at the tests of other open source PDKs.

What do we test?

  • Geometry polygons, layers and cell names.

  • Component Settings.

import pytest
from pytest_regressions.data_regression import DataRegressionFixture

from gdsfactory.difftest import difftest
from gdsfactory.samples.pdk.fab_c import cells

cell_names = list(cells.keys())
dirpath = pathlib.Path(__file__).absolute().with_suffix(".gds")

@pytest.fixture(params=cell_names, scope="function")
def component_name(request) -> str:
    return request.param

def test_gds(component_name: str) -> None:
    """Avoid regressions in GDS names, shapes and layers.

    Runs XOR and computes the area.

    component = cells[component_name]()
    test_name = f"fabc_{component_name}"
    difftest(component, test_name=test_name, dirpath=dirpath)

def test_settings(component_name: str, data_regression: DataRegressionFixture) -> None:
    """Avoid regressions in component settings and ports."""
    component = cells[component_name]()

For questions join the Join the chat at with or use GitHub issues or discussions.

Docker container#

As an alternative, you can use the pre-built Docker image from github

For instance, VS Code supports development inside a container. See Developing inside a Container for details.