// troubleshooting guide · hammerspoon
Hammerspoon v2: What Changes and Should You Wait
- Status
- Ongoing
- platforms:
- macOS
- updated:
- November 16, 2026
- reports:
- 2
- Method
- how we research
RUNBOOK · hammerspoon/hammerspoon-v2-javascript2 FIXES
// quick answer
Hammerspoon v2 is a Swift rewrite using JavaScript instead of Lua and was described as far from complete. Stay on v1 Lua for now.
Most likely fix: Stay on v1
How to fix it
// try these in order, the most common fix is first
FIX 1Stay on v1
- 01Use release 1.1.1 (macOS 13+)
- 02Keep your config in version control
Did this fix it?FIX 2Follow the project
- 01Watch the GitHub releases and the Google Group announcements
Did this fix it?
Symptoms
Users ask if Lua configs will break and whether the project is still alive.
Why it happens
- C-01Maintainer capacity is small
- C-02v1 architecture hard to build
// this guide also covers
- hammerspoon v2
- is hammerspoon dead
Still not working?
If Hammerspoon keeps failing, you're not alone. See every Hammerspoon problem users report or the alternatives people switch to.
Done fighting Hammerspoon? Our small team builds your own Hammerspoon alternative, or any software you need: web, mobile, games, desktop. Price agreed together.
Talk to usOther Hammerspoon errors
- Hammerspoon Accessibility Permission Not Working
- Hammerspoon Keystrokes Not Working
- Hammerspoon Hotkeys Stop Working
- Hammerspoon Timer or Watcher Stops Working
- Hammerspoon Modal Hotkeys Not Working
- Hammerspoon UI Not Showing in Full-Screen Apps
- Hammerspoon Cannot Find Application By Name
- Hammerspoon selectMenuItem Not Working From Console