---
title: "Getting started guide"
canonical_url: https://developer.repebble.com/pebbleos/docs/getting_started/
last_updated: 2026-10-21
sdk_version: 4.33.1
---
# Getting started guide

Source: https://developer.repebble.com/pebbleos/docs/getting_started/

This guide takes you from a fresh machine to PebbleOS running, in the emulator or on a watch.

## Install dependencies

Install the packages the build needs from your system’s package manager.

 Ubuntu

Ubuntu 24.04 LTS or later:

```
sudo apt update
sudo apt install \bison \clang \cmake \flex \gcc \gcc-multilib \gettext \git \gperf \libfreetype6-dev \libglib2.0-dev \libgtk-3-dev \libncurses-dev \librsvg2-bin \libsdl2-dev \make \nodejs \openocd \pkg-config \python3-dev \python3-venv
```

 Fedora

Fedora 44 or later:

```
sudo dnf upgrade --refresh
sudo dnf install \bison \clang \cmake \dash \flex \freetype-devel \gcc \gettext \git \glib2-devel \gperf \gtk3-devel \librsvg2-tools \make \ncurses-devel \nodejs \openocd \pkgconf-pkg-config \python3-devel \SDL2-devel
```

 macOS

Install [Homebrew](https://brew.sh/), then Python, Git and OpenOCD:

```
brew install python git openocd
brew link python@3
```

The remaining packages are listed in the repository and installed once it is cloned, in the next step.

## Get the source code

Clone the repository with its submodules and enter it:

```
git clone --recurse-submodules https://github.com/coredevices/pebbleoscd pebbleos
```

 Ubuntu

Nothing else to install.

 Fedora

Nothing else to install.

 macOS

Install the remaining packages:

```
brew install $(cat requirements-brew.txt)
```

## Install Python dependencies

Create a [virtual environment](https://docs.python.org/3/library/venv.html) in the checkout, activate it and install the Python dependencies:

```
python3 -m venv .venvsource .venv/bin/activate
pip install -r requirements.txt
```

This also installs [pbl](https://developer.repebble.com/pebbleos/docs/pbl.md), the developer command line the rest of this guide uses.

Tip

Activate the virtual environment (`source .venv/bin/activate`) in every new shell before running `pbl`.

## Install the PebbleOS SDK

The [PebbleOS SDK](https://github.com/coredevices/PebbleOS-SDK) provides the toolchain and tools the build needs:

```
curl -LsSf https://github.com/coredevices/PebbleOS-SDK/releases/latest/download/pebbleos-sdk-installer.sh | sh
```

The build finds the installed SDK on its own; [Build system](https://developer.repebble.com/pebbleos/docs/development/build_system.md) explains how to pick a specific one.

## Build for a board

Every build targets a board, either an emulated watch such as `qemu_emery` or a real one; [Boards](https://developer.repebble.com/pebbleos/docs/boards.md) lists them. Configure a build directory for one and build it:

```
pbl configure --board qemu_emery
pbl build
```

## Run the firmware

 Emulator

Launch the emulator:

```
pbl qemu
```

A window opens with the emulated watch and the firmware boots to the watchface; the arrow keys are the watch buttons. The [Emulator](https://developer.repebble.com/pebbleos/docs/development/emulation/emulator.md) page covers everything else you can do with it.

 Watch

There are two ways to get the firmware onto a watch:

- **Flash it with a programmer.** With a [programmer](https://developer.repebble.com/pebbleos/docs/programmers.md) connected as the [board’s page](https://developer.repebble.com/pebbleos/docs/boards.md) shows, [pbl flash](https://developer.repebble.com/pebbleos/docs/pbl/flash.md) writes the firmware directly:

- **Sideload a bundle.** Without a programmer, package the firmware with [pbl bundle](https://developer.repebble.com/pebbleos/docs/pbl/bundle.md), which writes a `.pbz` into the build directory:

Note

Holding Back + Up + Select reboots the watch into the recovery firmware (PRF), from which the Pebble mobile app can install a firmware again.

## Next steps

- [The pbl CLI](https://developer.repebble.com/pebbleos/docs/pbl.md) documents every `pbl` command.

- [Emulator and simulator](https://developer.repebble.com/pebbleos/docs/development/emulation.md) compares the emulator and the native simulator.

- [Testing](https://developer.repebble.com/pebbleos/docs/development/tests.md) covers the unit and integration test suites.

- [Architecture overview](https://developer.repebble.com/pebbleos/docs/architecture.md) explains how the firmware is put together.

Generated from PebbleOS [3a7b71785](https://github.com/coredevices/pebbleos/commit/3a7b71785fd439666c4a8bc116f561140e8dec01). This page is maintained in the pebbleos repository: [docs/getting\_started/index.md](https://github.com/coredevices/pebbleos/blob/3a7b71785fd439666c4a8bc116f561140e8dec01/docs/getting_started/index.md).