---
name: firefox-optimization
category: productivity
description: Firefox diagnostics, performance tuning, and GPU troubleshooting on Linux — NVIDIA/Wayland fixes, about:config optimization, VA-API video decoding.
---

# Firefox Optimization (Linux / NVIDIA / Wayland)

Diagnose and fix Firefox performance issues on Linux, then apply sustained tuning via user.js.

## Trigger

Use when the user reports Firefox lag (pages, video, scrolling), wants browser speed improvements, or needs GPU acceleration working on NVIDIA + Wayland.

## Workflow

### Phase 1: Diagnose (find the bottleneck)

```bash
# 1. Check if Firefox uses GPU at all
nvidia-smi | grep -i firefox
# Empty = software rendering fallback = root cause

# 2. Check key about:config prefs
grep -E "layers.acceleration|gfx.webrender|media.hardware" ~/.config/mozilla/firefox/*.default-release/prefs.js | head -10

# 3. Check display server / compositor
ps aux | grep -E "kwin_wayland|kwin_x11|Xwayland" | grep -v grep
echo "$XDG_SESSION_TYPE"

# 4. Check VA-API / nvidia-vaapi-driver
ls /usr/lib/dri/nvidia_drv_video.so 2>/dev/null && echo "NVIDIA VA-API driver present" || echo "Missing"
```

### Phase 2: NVIDIA + Wayland specific fixes

**Root cause pattern:** NVIDIA driver upgrade (especially 595→610 series) + Firefox + KWin Wayland can cause Firefox to fall back to software rendering. Key evidence: **0 MiB GPU memory** in nvidia-smi.

**Fix sequence:**

1. **Override `layers.acceleration.force-enabled` to `false`** in user.js — this pref is marked `do_not_use_directly` in Mozilla source and forces software fallback on NVIDIA 610 + Wayland when set to `true`.

2. **Enable VA-API hardware video decoding** (requires `libva-nvidia-driver` package):
   - `media.ffmpeg.vaapi.enabled = true`
   - `media.rdd-ffmpeg.enabled = true`
   - `media.ffmpeg.vaapi-drm-display.enabled = true`

3. **Force native Wayland** (not XWayland):
   - Create `~/.config/plasma-workspace/env/moz-wayland.sh` with `export MOZ_ENABLE_WAYLAND=1`
   - Also add to `~/.config/environment.d/moz-fix.conf`

4. **Enable GPU optimizations:**
   - `gfx.webrender.layer-compositor = true` (YouTube compositor optimization)
   - `gfx.canvas.accelerated = true`
   - `media.hardware-video-decoding.enabled = true`
   - `webgl.out-of-process = true`

### Phase 3: Research-backed optimization

**Sources (in order of authority):**
1. **Mozilla Gecko source** — raw.githubusercontent.com/mozilla/gecko-dev/master/modules/libpref/init/StaticPrefList.yaml — verify actual defaults and platform guards (e.g. `gfx.webrender.force-angle` is `#ifdef XP_WIN` — no-op on Linux)
2. **Betterfox/Fastfox** (github.com/yokoffing/Betterfox) — performance-focused fork, Fastfox.js contains networking/GPU/cache tuning
3. **arkenfox user.js** (github.com/arkenfox/user.js) — privacy/security reference, but many prefs trade performance for privacy

**Important verification pattern:** When researching a pref, check whether it's platform-gated in the Mozilla source before applying. Many prefs labeled "performance" are Windows-only.

### Phase 4: Apply via user.js

```js
// Backup first
cp user.js user.js.backup.$(date +%s)

// user.js overrides prefs.js — user_pref() in user.js wins
// Write all prefs to ~/.config/mozilla/firefox/*.default-release/user.js

// Verify:
grep -c "user_pref(" user.js           // count prefs
grep -v "^user_pref.*;$" user.js | grep -v "^//" | grep -v "^$"  // should be empty
```

### Phase 5: Verify

1. User logs out/back in (for MOZ_ENABLE_WAYLAND=1 env var)
2. Open `about:support` and check:
   - **Compositing:** `WebRender` (not `Basic` or `Software`)
   - **GPU #1:** NVIDIA (not `llvmpipe`)
   - **GPU Memory:** >0 MiB
   - **VAAPI:** `true`
3. `nvidia-smi` should show Firefox process with GPU memory >0

## Key pitfalls

- **`layers.acceleration.force-enabled=true`** is the #1 cause of software fallback on NVIDIA 610 + Wayland. Default is `false`. Only override to `false` never to `true`.
- **`gfx.webrender.force-angle` is Windows-only** — verified from Mozilla StaticPrefList.yaml `#ifdef XP_WIN`. Setting it on Linux is a no-op.
- **Disk cache `browser.cache.disk.enable = false`** (arkenfox default) hurts performance on SSDs. Prefer enabling with `browser.cache.disk.capacity = 512000` instead.
- **Disabling speculative connections** (prefetch, DNS prefetch, URL bar speculation) saves data but makes browsing feel slower. Only disable if the user explicitly wants privacy over speed.
- **Firefox ML/AI features** (`browser.ml.enable`) consume background CPU — safe to disable for speed.
- **Environment variables** in `~/.config/environment.d/*.conf` only apply to systemd user services. For GUI-launched apps (panel, desktop shortcuts), also write to `~/.config/plasma-workspace/env/*.sh`.

## Pref categories for optimization

| Category | Pref pattern | Goal |
|----------|-------------|------|
| GPU/WebRender | `gfx.webrender.*`, `gfx.canvas.*` | Enable hardware compositing |
| Network | `network.http.max-connections`, `network.dnsCache*`, `network.ssl_tokens_cache_capacity` | Faster page loads |
| Cache (disk) | `browser.cache.disk.capacity`, `browser.cache.memory.capacity` | Reduce re-downloads |
| Cache (media) | `media.cache_readahead_limit`, `media.cache_resume_threshold` | Buffer more video |
| Content processes | `dom.ipc.processCount`, `dom.ipc.processCount.webIsolated` | Tab isolation |
| Telemetry kill | `toolkit.telemetry.*`, `datareporting.*`, `app.shield.*` | Free background CPU |
| Promo removal | `browser.discovery.*`, `browser.newtabpage.activity-stream.asrouter.*` | Remove bloat |
| Scrolling | `general.smoothScroll.*`, `mousewheel.*` | Smoothness |
| Security | `dom.security.https_only_mode`, `security.mixed_content.*` | Safe defaults |
| Privacy | `permissions.default.*`, `media.autoplay.default`, `beacon.enabled` | Block annoyances |