Skip to content
Get packs

Guide · Open source

How to use Hammerspoon: install it and write your first init.lua

Updated · written with AI from the project's own documentation and checked against our catalogue data

Hammerspoon is a macOS automation tool that connects the operating system to a Lua scripting engine. It ships with extensions that expose many system features, but it does nothing until you write a configuration file. This guide shows you how to install it and set up the file that controls its behaviour.

HammerspoonHammerspoon/hammerspoon · ★ 16.4k · MIT

Quick start

  1. 1Install Hammerspoon. Run brew install hammerspoon --cask, or download the latest release and move Hammerspoon.app to Applications.
  2. 2Open the app. Launch Hammerspoon from Applications. It does nothing yet because no configuration exists.
  3. 3Create the config folder. Make a folder called .hammerspoon in your home directory, which is ~/.hammerspoon/.
  4. 4Create init.lua. Inside that folder, create a file named init.lua. Hammerspoon reads this file for its instructions.
  5. 5Write Lua code. Add Lua that calls Hammerspoon extensions, using the API docs as a reference.
  6. 6Test and iterate. Reload the configuration, check that the behaviour is what you expect, and refine the script from there.

What Hammerspoon is and who it is for

At its core, Hammerspoon is a bridge between macOS and a Lua scripting engine. Its power comes from a set of extensions that expose specific pieces of system functionality, which your Lua scripts can then control.

It suits Mac users comfortable writing small scripts who want custom keyboard shortcuts or window behaviour, and developers who want to script their own macOS environment. It is not a ready-made app with no configuration.

Install Hammerspoon on macOS with Homebrew or manually

The project's README gives two methods. With Homebrew, run the command below. To install manually, download the latest release from the project's releases page, then drag Hammerspoon.app from your Downloads folder to Applications.

  • Prerequisite: macOS. Hammerspoon is macOS only.
brew install hammerspoon --cask

Create your init.lua configuration file

Out of the box, Hammerspoon does nothing. You control its behaviour by creating a file named init.lua inside a hidden folder in your home directory. Hammerspoon reads this file, so everything you want it to do goes here.

  • Create the folder ~/.hammerspoon/
  • Create the file ~/.hammerspoon/init.lua
  • Add Lua code to it, then reload Hammerspoon to apply changes
~/.hammerspoon/init.lua

Write your first Lua script

Your configuration is ordinary Lua code that calls Hammerspoon's extensions. The official Getting Started Guide and API docs describe the available modules and functions. Start with a small change, confirm it works, then add more.

  • Use the API docs at hammerspoon.org/docs to look up which extension handles the feature you want
  • Browse the community Sample Configurations wiki page for working examples
  • Keep each change small so problems are easy to trace

Find help when you get stuck

The project lists several support resources. The Getting Started Guide and FAQ cover common setup questions. For live help, there is an IRC channel (#hammerspoon on Libera) and a Google Group for support. The project also has a Discord server and a Contribution Guide for developers who want to get involved.

What people use it for

  • Custom keyboard shortcuts that trigger actions on your Mac
  • Window behaviour customisation through scripts
  • Automating repetitive desktop tasks on macOS
  • Scripting your own macOS development environment

Frequently asked questions

Is Hammerspoon free?

Hammerspoon is open source and released under the MIT licence. The source material does not mention any paid tier.

How do I install Hammerspoon?

Install it with Homebrew using brew install hammerspoon --cask, or download the latest release and drag Hammerspoon.app from Downloads to Applications.

Does Hammerspoon work on Windows or Linux?

No. Hammerspoon is for macOS only, so users on other operating systems cannot use it.

Why does Hammerspoon do nothing after I install it?

Hammerspoon has no built-in behaviour. You need to create ~/.hammerspoon/init.lua and write Lua code telling it what to do.

Do I need to know Lua to use Hammerspoon?

Yes, in practice. Scripting is the main way to use Hammerspoon, so basic Lua knowledge is needed.

How is Hammerspoon different from Mjolnir?

Hammerspoon is a fork of Mjolnir. Mjolnir is minimal and hosts its extensions externally through a Lua package manager, while Hammerspoon aims for a more integrated experience with built-in extensions.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Hammerspoon suits Mac users and developers who are willing to write Lua and want deep, scriptable control over their desktop. If you want a ready-made app that works without configuration, or you use another operating system, pick a different tool such as Rectangle or Karabiner-Elements for simpler needs.

Install options & downloads