awesome/docs/09-options.md

Startup options

This document explains how to control how AwesomeWM behaves before rc.lua is executed.

Command line

AwesomeWM has the following command line options:

Usage: awesome [OPTION]
  -h, --help             show help
  -v, --version          show version
  -c, --config FILE      configuration file to use
  -f  --force            ignore modelines and apply the command line arguments
  -s, --search DIR       add a directory to the library search path
  -k, --check            check configuration file syntax
  -a, --no-argb          disable client transparency support
  -l  --api-level LEVEL  select a different API support level than the current version
  -m, --screen on|off    enable or disable automatic screen creation (default: on)
  -r, --replace          replace an existing window manager

Modelines

Usually, AwesomeWM is started using a session manager rather than directly using the command line. On top of that, to make rc.lua more portable, it is possible to set many of those options directly in your config file. They will be interpreted before the Lua virtual machine is started. The keys are:

Name	Has argument	Allow many	Type	Description
search	Yes	Yes	string	Path where the AwesomeWM core libraries are located
no-argb	No	No	N/A	Disable built-in (real) transparency.
api-level	Yes	No	integer	The config API level.
screen	Yes	No	string	Create the screen before executing `rc.lua` (`on` or `off`)
replace	No	No	N/A	Replace the current window manager.

A modeline must be near the top of rc.lua and start with -- awesome_mode:. The options are separated by :. If an option has a value, it is separated by =. The default modeline is:

-- awesome_mode: api-level=4:screen=on

To display more deprecation errors, you can increase the API level by 2:

-- awesome_mode: api-level=6:screen=on

#! (shebang) support.

It is possible to make some .lua file executable and use the POSIX magic prefix (#!, often referred as the shebang operator). AwesomeWM will attempt to parse the header. Note that for now UTF-8 paths are not supported. A typical file header will look like:

#! /usr/bin/env awesome --replace
-- If LuaRocks is installed, make sure that packages installed through it
-- are found (e.g. lgi). If LuaRocks is not installed, do nothing.
pcall(require, "luarocks.loader")

-- Standard awesome library
local gears = require("gears")
[... more `rc.lua` content ...]

Then you can make the script executable with chmod +x and run it.

Options description

version (-v)

Command line	Modeline	Shebang
Yes	No	No

The typical output will look like:

awesome v4.3 (Too long)
  • Compiled against Lua 5.1.5 (running with Lua 5.1)
  • API level: 4
  • D-Bus support: yes
  • xcb-errors support: no
  • execinfo support: yes
  • xcb-randr version: 1.6
  • LGI version: 0.9.2
  • Transparency enabled: yes
  • Custom search paths: no

The content is useful when reporting a bug.

config (-c): Alternate config path.

Command line	Modeline	Shebang
Yes	No	No

This option allows to pass an arbitrary Lua file to be used as a config rather than ~/.config/awesome/rc.lua or /etc/xdg/awesome/rc.lua. It makes zero sense in the shebang since you invoke a script directly. It doesn't make sense in the modeline either since at that point the file is already being read.

force (-f): Use the command line arguments even when the modeline disagree.

Command line	Modeline	Shebang
Yes	No	No

Usually, modelines have the final say of which options to enable. This allows rc.lua to be portable between computers without have to modify ~/.xinitrc or your session files. However, sometime, it is useful to override these parameters. The most common use case is the to bump the API level to see more deprecation warnings.

search (-s): Add directories to the Lua search paths.

Command line	Modeline	Shebang
Yes	Yes	Yes

This option allows to add more paths to the Lua search path. It can be used to set an alternate version of the core libraries such as awful to make upstream patches development easier. It can also be used to point to custom modules. It is usually recommended to place custom modules in ~/.config/awesome/ or /usr/share/awesome/lib. Again, this option is mostly useful for development.

check (-k): Check the config SYNTAX.

Command line	Modeline	Shebang
Yes	No	No

This option only check if the file is a valid Lua script. It will not check if your custom logic makes sense. Even when this option says your config is fine, it does NOT mean it can load properly. It only means it can be parsed and the interpreter can attempt to execute it.

no-argb (-a): Mitigate buggy graphics drivers.

Command line	Modeline	Shebang
Yes	Yes	Yes

This option disables the built-in real transparency support. This means titlebars and wiboxes can no longer be made fully transparent. If you don't use a compositing manager such as compton or picom, this will only improve reliability and portability. Transparency is enabled by default and this should only be used when your config misbehave with a popular graphics driver. If it does, please notify them. The bug is on their side.

api-level (-l): Force your config to use a different API version.

Command line	Modeline	Shebang
Yes	Yes	Yes

If you invested a lot of effort into a configuration and a new major version is AwesomeWM is released, you might want to postpone having to update everything until you are ready to begin using the new features. If the API level is set, AwesomeWM will try to honor the behavior and content of the previous APIs.

You can also set this value forward to get notified faster of your usage of newly deprecated API and enjoy cutting edge experimental features.

The default API level matches the first component of the AwesomeWM version. For example, AwesomeWM v4.3 API level is "4". This only goes back to AwesomeWM 4.0. The older 3.x APIs have been removed.

screen (-m): Set the screen creation behavior.

Command line	Modeline	Shebang
Yes	Yes	Yes

This option changes when screen objects are created. In AwesomeWM 4.x, by default, they are created before rc.lua is parsed. This is very convenient for setup where the number of screen never changes. By creating them before rc.lua, it is possible to make many assumptions such as mouse.screen and awful.screen.focused() to always point to a valid screen. This is the on behavior. The main downside is that when the number of screen changes or when the DPI must be modified, all the automatic magic becomes very inconvenient.

When set to off, the screens are created early when executing rc.lua. This has the advantages of sending multiple signals and giving a lot more configuration options for features like the DPI or ultra-wide monitor. It also make it easier to add and remove screens dynamically since they are fully. In the future, the default will be off to allow HiDPI support to be enabled by default. controllable by Lua code.

replace (-r): Replace the current window manager with AwesomeWM.

Command line	Modeline	Shebang
Yes	Yes	Yes

If this option is set, AwesomeWM will kill the current window manager (even if it is another awesome instance and replace it. This is disabled by default.