Local install

Previous Next

Install GDSFactory+ on your local machine to design photonic chips directly from VSCode.

Prefer cloud? If you have access to GDSFactory+ Cloud workspaces, see the Cloud Setup guide instead.

Prerequisites

Before you begin, make sure you have:

Step 1: Download a Sample Project

Open VSCode and run this command in the terminal to clone the Cornerstone PDK sample project:

git clone https://github.com/gdsfactory/gdsfactory_sample_project

Alternative: Download the project as a zip file from GitHub and extract it to your working directory.

Once downloaded, open the project folder in VSCode:

  1. Click File → Open Folder
  2. Select the gdsfactory_sample_project folder

Step 2: Install the GDSFactory+ Extension

Install from VSCode

  1. Click the Extensions icon in the left sidebar
  2. Search for GDSFactory+
  3. Click Install

extensions

Install from the Marketplace

Alternatively, install directly from the VSCode Marketplace website.

After installation, you'll see a new GF+ icon in the left sidebar:

Left sidebar icons

Step 3: Verify Your Setup

Click the GF+ icon to open the extension panel. The Status section shows several checks:

GF+ panel status

✅ All green? You're ready to go! Skip to Next Steps.

❌ Any red checks? Follow the instructions in the panel to fix them. You may need to restart VSCode after making changes.

Common Setup Issues

UV Not Installed

GDSFactory+ uses uv to manage Python environments.

How to install: Follow the official uv installation guide.

API Key Missing

You need an API key to use GDSFactory+.

If you have an account:

  1. Go to the GDSFactory+ Customer Portal
  2. Click API Keys in the left sidebar
  3. Click + New API Key
  4. Name your key and save it
  5. Click the eye icon to view the key
  6. Copy the key and paste it into the GF+ extension when prompted

Your API key is stored in:

  • macOS/Linux: ~/.gdsfactoryplus/gdsfactoryplus.toml
  • Windows: C:\Users\<YourUsername>\.gdsfactoryplus\gdsfactoryplus.toml

Don't have an account?

  • Sign up here
  • Or contact your organization admin if you're part of a team

Organization Admins: Watch this video to learn how to invite team members.

PDK Not Installed

GDSFactory+ automatically manages dependencies using the pyproject.toml file in your project folder.

The sample project includes these lines:

[tool.gdsfactoryplus.pdk]
name = "cspdk.si220.cband"

This tells GDSFactory+ to use the Cornerstone PDK.

Version Mismatch

The VSCode extension and Python package versions must match.

If the Python package is older:

  • Update the VSCode extension from the Extensions menu

If the VSCode extension is older:

  • Click Create environment in the Status section of the GF+ panel

Still having issues?

  • Make sure you've opened the correct folder (File → Open Folder → select gdsfactory_sample_project)

Extension Menu Overview

The top menu in the GF+ panel provides tools to manage your project:

Settings menu

  • Settings: Configure API keys and project settings
  • New Project: Create a project from a template
  • Reload: Refresh the current project
  • Build: Build project components

Next Steps

Once all status checks are green, you're ready to start designing!

Get started:

  • Follow the Quickstart Guide to design your first circuit using the Cornerstone PDK

Use a different PDK:

Need help?

GDSFactory+ Cloud setup