# Requirements

**Conky Studio** ships as an AppImage: it does not need `sudo` or a package manager to run the app itself.  
**Conky** (and a few optional system tools) come from your distro. Built themes run with **zero dependency on Conky Studio** — only Conky and whatever tools your nodes use.

Studio also **detects your environment** (Tools → Hardware & Session), resolves Canvas window settings, and **warns** before Live Preview / Start when overlays are unlikely to work. See [Compatibility](Compatibility.md) for display servers and compositors.

---

## What the application needs

### Always required

| Component | Why |
|-----------|-----|
| **Conky Studio AppImage** | The authoring UI (Python/PyQt6 bundled inside the AppImage) |
| **Conky** | Live Preview and every built theme launch `conky` |
| **Graphical session** | X11, or Wayland on a [supported compositor](Compatibility.md) |
| **Lua + Cairo in Conky** | All HUD drawing goes through Conky’s Lua/Cairo path (`lua-cairo`) |

Check Conky:

```
conky -v
```

On Wayland, prefer a build that **lists Wayland** in that output. Some distro packages are still X11-only; Studio will warn if it detects a Wayland session with an X11-only binary.

### Strongly recommended

| Component | Why |
|-----------|-----|
| **A compositor** (picom, or your DE’s built-in) | True per-pixel transparency (`own_window_argb_*`) |
| **fontconfig** (`fc-list`, `fc-cache`) | Font picker in the property panel; Tools → Install Font |

### Optional (only if you use those nodes/features)

| Component | Used for |
|-----------|----------|
| **lm-sensors** (`sensors`) | CPU / board temperature sources |
| **playerctl** | Now Playing, Album Art, playback status |
| **curl** | Weather (wttr.in), Public IP |
| **nvidia-smi** *or* AMD sysfs (`/sys/class/drm/...`) | GPU util/temp/VRAM |
| **smartctl** | Disk temperature (often needs permissions) |
| **RSVG support in Conky** | SVG Image / Icon nodes (PNGs work without it) |

Themes that use Weather or Public IP list `curl` in their generated `theme.json` `requires` array. CPU temp, GPU, music, etc. simply read blank or zero until the matching tool is present — the rest of the HUD still runs.

### Not required

- No separate Studio runtime after a theme is built  
- No mandatory internet for local design / Build & Install  
- No `appimaged` (the AppImage can self-install a desktop entry + icon)  
- No extra Cairo/Lua packages beyond what your Conky package already provides  

---

## Distro install commands

Install **Conky** first. Add optional packages only for the sensors/music/weather nodes you care about.

### Debian / Ubuntu / Linux Mint / Pop!_OS (apt)

**Required**

```
sudo apt update
sudo apt install conky-all
```

`conky-all` is preferred over minimal `conky` packages when available (more bindings).

**Optional**

```
sudo apt install lm-sensors playerctl curl
sudo sensors-detect   # once; follow prompts for hardware sensors
```

---

### Fedora (dnf)

**Required**

```
sudo dnf install conky
```

**Optional**

```
sudo dnf install lm_sensors playerctl curl
sudo sensors-detect
```

---

### RHEL / CentOS Stream / Alma / Rocky (dnf)

**Required** (EPEL is often needed for Conky)

```
sudo dnf install epel-release
sudo dnf install conky
```

**Optional**

```
sudo dnf install lm_sensors playerctl curl
sudo sensors-detect
```

---

### openSUSE Leap / Tumbleweed (zypper)

**Required**

```
sudo zypper install conky
```

**Optional**

```
sudo zypper install sensors playerctl curl
sudo sensors-detect
```

---

### Arch Linux / Manjaro / EndeavourOS (pacman)

**Required**

```
sudo pacman -S conky
```

**Optional**

```
sudo pacman -S lm_sensors playerctl curl
sudo sensors-detect
```

---

### Void Linux (xbps)

**Required**

```
sudo xbps-install -S conky
```

**Optional**

```
sudo xbps-install -S lm_sensors playerctl curl
```

---

### Gentoo (emerge)

**Required** — enable the USE flags you need (e.g. `wayland`, `X`, `lua`):

```
sudo emerge --ask app-admin/conky
```

**Optional**

```
sudo emerge --ask sys-apps/lm-sensors media-sound/playerctl net-misc/curl
sudo sensors-detect
```

---

### Alpine (apk)

**Required**

```
sudo apk add conky
```

**Optional**

```
sudo apk add lm-sensors playerctl curl
```

---

## What Studio does with these dependencies

| Situation | Behaviour |
|-----------|-----------|
| Conky missing or not on `PATH` | Hardware & Session severity **block**; Live Preview/Start need `conky` |
| Wayland session + X11-only Conky | **Warn**; overlays may fail or only work under XWayland |
| GNOME Mutter Wayland | **Block** for desktop overlays (compositor limit) — see [Compatibility](Compatibility.md) |
| lm-sensors/GPU tools missing | Related sources read blank or `0`; other nodes still draw |
| playerctl/curl missing | Music/weather/public-IP nodes fail or stay empty until installed |
| Fonts missing on another machine | Theme falls back to system defaults; install fonts on the target PC or use Tools → Install Font while authoring |

After **Build & Install**, the theme folder under `~/.config/conky/<Name>/` is self-contained: `start.sh`, `conky.conf`, `render.lua`, `scripts/`, `images/`. Launch with `./start.sh` or the Manager tab — Conky Studio does not need to stay open.

---

## Quick verification

```
conky -v                    # installed? Wayland listed?
which sensors playerctl curl 2>/dev/null
echo "$XDG_SESSION_TYPE"    # x11 or wayland
```

Then in Studio: **Tools → Hardware & Session** for the full structured report (display server, desktop, layer-shell likelihood, Conky path, GPU hint, guidance).

See also [Compatibility](Compatibility.md).