---
title: "Installing the Pebble SDK"
canonical_url: https://developer.repebble.com/sdk/
last_updated: 2026-10-11
sdk_version: 4.33.1
---
# Installing the Pebble SDK

Source: https://developer.repebble.com/sdk/

The easiest way to start building a Pebble watchface or app is with [CloudPebble](https://cloudpebble.repebble.com) - no installation required. It runs entirely in your browser!

Otherwise, if you are somewhat command-line knowledgeable, you can follow the instructions below to install the SDK locally on your computer.

## Install dependencies

#### MacOS

You will need to install Node.js and libpng. The easiest way is with [Homebrew](https://brew.sh/):

```
brew install node libpng
```

#### Ubuntu

You will need to install a few dependencies to make the SDK run:

```
sudo apt install nodejs npm libsdl2-2.0-0 libglib2.0-0 libpixman-1-0 zlib1g libsndio7.0
```

> Note: if you already have `node` installed, you can install only:

```
sudo apt install libsdl2-2.0-0 libglib2.0-0 libpixman-1-0 zlib1g libsndio7.0
```

#### Fedora

```
sudo dnf install nodejs SDL2 glib2 pixman zlib sndio
```

#### Windows

The Pebble SDK does not run on Windows, but you can use WSL. Install Ubuntu in WSL, and then use the instructions above to install dependencies.

## Download the Pebble CLI

Install [uv](https://docs.astral.sh/uv/getting-started/installation/), a fast package manager for Python.

Then, run:

```
uv tool install pebble-tool
```

> Note: The `pebble` tool requires Python 3.10 to 3.13. Python 3.14 is not supported yet.

Not every language and feature is available on every watch. See the platform support table in [_Hardware Information_](https://developer.repebble.com/guides/tools-and-resources/hardware-information.md).

The `sdkVersion` field in `package.json` stays `"3"` for every app, including apps built with SDK 4.x. The version of the `pebble` tool (5.x) is not the version of the SDK (4.x); run `pebble sdk list` to see which SDKs are installed.

## Next Steps

Now that you have the Pebble SDK downloaded and installed on your computer, it is time to create your first app!

#### Create a Pebble app

Install the latest SDK:

```
pebble sdk install latest
```

Create a project (for example, called myproject):

```
pebble new-project myproject
```

Compile the project (after `cd`ing to your project directory):

```
pebble build
```

Install the app on an emulator for the Pebble Time:

```
pebble install --emulator basalt
```

Or, install the app on the watch through the Pebble mobile app (install it from [repebble.com/app](https://repebble.com/app)). In the Pebble mobile app, sign in with your Pebble account, open the _Devices_ tab, tap the three dot icon on your watch and enable the _Dev Connection_ toggle. Then, on your computer, sign in to the same Pebble account and install:

```
pebble login
pebble install --cloudpebble
```

See [_Developer Connection_](https://developer.repebble.com/guides/tools-and-resources/developer-connection.md) for details and for the LAN connection, which works without signing in.

#### Learn more

The best way to learn is by checking out our examples apps: [weather](https://github.com/pebble-examples/pebblekit-js-weather/), [simple game](https://github.com/pebble-hacks/pandas-and-bananas/), [concentricity watchface](https://github.com/pebble-examples/concentricity/), and [many more](https://developer.repebble.com/examples.md)! Or try [tutorials](https://developer.repebble.com/tutorials.md) for a step-by-step guide on how to write a simple C Pebble application.

#### Using an AI coding agent

`pebble new-project --ai myproject` also writes instruction files for Claude Code and Cursor, and every page of this site has a Markdown version for agents to read. See [_Building with AI Agents_](https://developer.repebble.com/guides/ai-agents.md) for the files, the documentation index at `/llms.txt` and the emulator commands an agent can use to check its work.

### Installation Problems?

On Linux, check the following first:

- On WSL2, install `build-essential` before installing the SDK: `sudo apt install build-essential`.
- The emulator needs glibc 2.38 or newer. Ubuntu 22.04 ships an older glibc, so use Ubuntu 24.04 or newer.
- On Fedora, the emulator needs `libsndio`: `sudo dnf install sndio`.

If the emulator gets into a strange state, for example it will not boot, keeps an app you have removed, or an install times out, run `pebble kill` to stop it and `pebble wipe` to reset its stored data, then install again.

Check the [FAQ](https://developer.repebble.com/faqs.md) next - common install, emulator, and `pebble` tool errors are answered there.

If you're still stuck, ask on the [Pebble Developer Forum](https://forum.repebble.com/c/developers-ask-questions-and-get-help/7). Please provide as many details as you can about the issues you may have encountered.

**Tip:** Copying and pasting commands from your Terminal output will help a great deal.