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.

Compatible Platforms

  1. Windows Subsystem for Linux (WSL)
  2. Windows Native (we recommend WSL for better performance)
  3. macOS (Apple Silicon)
  4. Linux (glibc 2.28 and up, e.g. RHEL 8+, Ubuntu 18.04+, Debian 10+)

Prerequisites

Before you begin, make sure you have:

  • VSCode installed, or another compatible code editor (antigravity)
  • MacOS users: Xcode installed
  • Windows users: We only recommend running the app inside WSL

Step 1: Install the GDSFactory+ Extension

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

extensions

Step 2: 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

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) or create a new project from a template using the New Project button in the GF+ panel

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