---
title: "Installation"
description: "Install Rosette, create a new project, and run the dev server."
canonical_url: "https://www.rosette.dev/docs/getting-started/installation"
markdown_url: "https://www.rosette.dev/docs/getting-started/installation.md"
source_url: "https://github.com/PreFab-Photonics/rosette/blob/f086d7670645fd36c05362d696d442a2b2e74850/www/content/docs/getting-started/installation.mdx"
docs_channel: "main"
docs_revision: "f086d7670645fd36c05362d696d442a2b2e74850"
---

# Installation

Create a new Rosette project and run it locally.

## System requirements

Before you begin, make sure your environment meets the following requirements:

* **Python 3.11 or later:** Rosette ships pre-built wheels for Python 3.11 through
  3.14. You can check your version with `python --version`.
* **Operating system:** macOS (Apple Silicon), Linux (x86\_64, aarch64), or Windows
  (x86\_64).
* **Package manager:** [uv](https://docs.astral.sh/uv/) is recommended for fast
  dependency management, but `pip` works too.

No Rust toolchain is required for normal use. Pre-compiled native extensions are
included in the published wheels.

## Quick start



### uv (recommended)

```bash
mkdir my-chip && cd my-chip
uv init
uv add librosette
uv run rosette init
uv run rosette serve
```





### pip

```bash
mkdir my-chip && cd my-chip
python -m venv .venv && source .venv/bin/activate
pip install librosette
rosette init
rosette serve
```

On Windows, activate the virtual environment with `.venv\Scripts\activate` instead.



This creates a new project, installs Rosette, scaffolds the project files, and starts
the dev server. Visit `http://localhost:5173/preview` to open the viewer.



> **Note: One-command start**
>
> `rosette init` can create the project directory and set up uv for you. Pass a
> path and, if there's no `pyproject.toml` yet, it runs `uv init --bare`,
> `uv add librosette`, and `git init` before scaffolding:
>
> ```bash
> uvx --from librosette rosette init my-chip
> cd my-chip
> ```
>
> Omit the path to initialize in the current directory instead. `uvx` runs the
> CLI in a throwaway environment, so this works before anything is installed (the
> package is `librosette` but the command is `rosette`, hence `--from`). Pass
> `--yes` to skip the confirmation prompt (useful in scripts), `--no-git` to skip
> repo initialization. If uv isn't installed, `rosette init` falls back to
> printing the manual pip steps.





> **Note: Package name**
>
> The official PyPI package is called
> [`librosette`](https://pypi.org/project/librosette/), but you import it as `rosette`
> in Python:
>
> ```python
> from rosette import Cell, Library
> ```



## Global CLI install

If you prefer having `rosette` available as a global command (without `uv run` prefix),
you can install it as a tool:

```bash
uv tool install librosette
```

This installs the `rosette` CLI into an isolated environment and makes it available
system-wide. A short alias `ro` is also available. You can then run commands directly:

```bash
rosette serve designs/my_design.py    # dev server with live preview
rosette build designs/my_design.py    # build to GDS
rosette build designs/my_design.py --check  # build with DRC pre-check
rosette check designs/my_design.py    # run all checks (DRC, ...)
rosette check designs/my_design.py --json  # machine-readable output (drc/dfm too)
rosette drc designs/my_design.py      # run DRC only
rosette run output/my_design.gds      # view a GDS file
rosette --version                     # print version

# or use the short alias
ro serve designs/my_design.py
```



> **Warning: Project dependency still needed**
>
> The global CLI install gives you the `rosette` command, but your design scripts still
> need `librosette` as a project dependency to resolve `from rosette import ...`. Make
> sure to also run `uv add librosette` in your project.



## Create a project

The quickest way to set up a new Rosette project is with `rosette init`. If you
prefer to set up the Python project yourself (rather than letting `rosette init`
bootstrap it), start by creating a directory and initializing a Python project:



### uv

```bash
mkdir my-chip && cd my-chip
uv init
uv add librosette
```





### pip

```bash
mkdir my-chip && cd my-chip
python -m venv .venv && source .venv/bin/activate
pip install librosette
```

On Windows, activate the virtual environment with `.venv\Scripts\activate` instead.



Then initialize Rosette:

```bash
rosette init
```



> **Note: Running rosette commands with uv**
>
> If you installed via `uv add librosette`, prefix every `rosette` command
> with `uv run` (for example, `uv run rosette init`). If you installed via
> `uv tool install librosette` or inside an activated `pip` venv, the
> `rosette` command is on your `PATH` directly. The rest of this page
> shows the bare form.



You will see the following prompts:

```txt
Select template:
    Blank    - Empty config, define your own layers
    Generic  - Pre-configured silicon photonics layers & DRC

Select AI tool:
    OpenCode    - Generates AGENTS.md
    Claude Code - Generates CLAUDE.md
    None        - Skip AI tool setup
```

The **generic** template is a good starting point if you are working with silicon
photonics. It comes with layer definitions and design-rule checks pre-configured. The
**blank** template gives you a clean slate.

## Project structure

After running `rosette init`, your project will contain:

```txt
my-chip/
├── rosette.toml          # Project config: layers, verification, and snapshots
├── designs/              # Your design scripts go here
├── output/               # GDS build output
├── components/           # Template-specific component source and documentation
│   ├── mmi.py
│   ├── ring.py
│   ├── grating_coupler.py
│   ├── .rosette-provenance.json # Copy baselines for upgrade checks
│   └── ...
├── .rosette/
│   ├── index.md          # Task-to-context router for agents
│   ├── contracts/        # Focused layout, routing, verification, and authoring APIs
│   ├── api.pyi           # Complete Python API fallback
│   ├── cli.json          # Complete machine-readable CLI fallback
│   └── manifest.json     # Managed-reference provenance
├── .agents/skills/       # Focused agent skills (or .claude/skills/)
└── AGENTS.md             # AI agent instructions (if selected)
```

* **`rosette.toml`**: the central configuration file. It defines project metadata,
  layers, verification, and snapshot retention. The **blank** template ships only a
  `[project]` section - add settings as needed using the complete
  [project configuration reference](/docs/guides/project-configuration).
* **`designs/`**: where you write your layout scripts. Each script defines cells and
  geometry that Rosette compiles to GDS-II.
* **`output/`**: build artifacts. Running `rosette build` writes GDS files here
  (and recreates the directory if you delete it). GDS files are gitignored by
  default since they're regenerated from your design scripts.
* **`components/`**: the project-local component API, including its catalog in
  `__init__.py`, implementation source, signatures, and docstrings. Components are
  template-specific: the generic template copies the standard photonic building
  blocks, while the blank template starts with only an empty scaffold and shared
  authoring utilities. Everything here is yours to read and modify.
* **`.rosette/index.md`**: the compact starting point for agents. It routes layout,
  routing, verification, and component-authoring tasks to focused contracts and skills.
* **`.rosette/contracts/`**: task-specific API slices generated from the authoritative
  public contract. They reduce default context without duplicating signatures.
* **`.rosette/api.pyi`**: the complete public Python API fallback for operations not
  covered by a focused contract.
* **`.rosette/cli.json`**: the complete machine-readable CLI fallback, including
  commands, flags, exit codes, and JSON output schemas. Agents read only the command
  entry they need.
* **`.rosette/manifest.json`**: package and contract provenance for the managed core
  references. Component provenance remains separate in
  `components/.rosette-provenance.json`, beside the component source, so upgrade
  checks survive fresh clones.

The `.rosette/` directory is gitignored because these references are tied to the
installed Rosette version. After a fresh clone, restore the managed references with
`uv run rosette update`. The command regenerates managed context while preserving
runtime snapshots and user-owned project files. Do not rerun `rosette init` in an
existing project.

## Run the dev server

Start the development server to get a live preview of your designs:

```bash
rosette serve designs/my_design.py
```

This opens a browser window at `http://localhost:5173/preview` with an interactive WebGPU
viewer. When you edit and save your design script, the viewer reloads automatically.

You can also build a design to a GDS file without the viewer:

```bash
rosette build designs/my_design.py
```

The output is written to `output/` by default. Add `--check` to run DRC before building:

```bash
rosette build designs/my_design.py --check
```

DRC results are printed but the build always proceeds. Use `rosette check` separately
if you want to enforce passing DRC.

## Building from source

If you want to contribute to Rosette or need to build from source, you will need
the Rust toolchain in addition to Python.

**Prerequisites:**

* [Rust](https://www.rust-lang.org/tools/install) (stable channel)
* Python 3.11+
* [uv](https://docs.astral.sh/uv/)

**Clone and build:**

```bash
git clone https://github.com/PreFab-Photonics/rosette.git
cd rosette
uv run maturin develop
```

This compiles the Rust core and installs the Python package in development mode. After
making changes to Rust code, re-run `uv run maturin develop` to rebuild.

**Run the test suite:**

```bash
cargo test && uv run pytest
```