Getting Started¶

Installation¶

Skim is a Python tool that can be installed using various package managers. We recommend using uv or pipx to install it in an isolated environment.

Using uv (Recommended)¶

uv tool install 'qmk-skim[playwright,cairo,tui]'

You can upgrade to a new version using:

uv tool upgrade qmk-skim

Using pipx¶

pipx install 'qmk-skim[playwright,cairo,tui]'

Using pip¶

pip install 'qmk-skim[playwright,cairo,tui]'

System Dependencies¶

Skim generates SVG images by default, which requires no external dependencies. However, if you want to generate raster images (PNG, JPEG, WEBP, AVIF), you need to install additional software.

Chromium (Playwright)¶

To use the Chromium render engine (recommended for best quality):

Install the package with the playwright extra (if using pip):
```
pip install "qmk-skim[playwright]"
```
Install the browser binaries:
```
playwright install chromium
```

Cairo¶

To use the Cairo render engine:

macOS: Install cairo via Homebrew:
```
brew install cairo
```
Linux (Debian/Ubuntu): Install libcairo2:
```
sudo apt-get install libcairo2
```
Windows: GTK+ runtime is required (instructions vary).

Checking Your Setup¶

After installation, run the doctor command to verify your environment:

skim doctor

This checks for available render engines (Chromium, Cairo) and reports any missing optional dependencies.

Quick Start¶

Launch the interactive configurator:

The easiest way to create a configuration file is the interactive TUI:
```
skim configure --interactive
```
This opens a tabbed interface where you can set layer names, colors, keycodes, and styling options. Save with Ctrl+S.
Or generate a config from a keymap:

If you have a Keybard, Vial, or QMK c2json file, extract a config from it:
```
skim configure --keymap my-keymap.kbi --output skim-config.yaml
```
Generate images:
```
skim generate --keymap my-keymap.kbi --config skim-config.yaml
```
This generates SVG images for all layers plus an overview in the current directory.

Explore options:

skim generate --help
skim configure --help