Main configuration file

The main configuration file is by default called wireplumber.conf. This can be changed on the command line by passing the --config-file or -c option:

wireplumber --config-file=bluetooth.conf

The --config-file option is useful to run multiple instances of wireplumber that do separate tasks each. For more information on this subject, see the Multiple Instances section.

The format of this configuration file is the variant of JSON that is also used in PipeWire configuration files. Note that this is subject to change in the future.

All sections are essentially JSON objects. Lines starting with # are treated as comments and ignored. The list of all possible section JSON objects are:


    Used to define properties to configure the PipeWire context and some modules.

    Example: = { = WirePlumber
      log.level = 2

    This sets the daemon’s name to WirePlumber and the log level to 2, which only displays errors and warnings. See the Debug Logging section for more details.


    Used to find spa factory names. It maps a spa factory name regular expression to a library name that should contain that factory. The object property names are the regular expression, and the object property values are the actual library name:

    <factory-name regex> = <library-name>

    Example: = {
      api.alsa.*      = alsa/libspa-alsa
      audio.convert.* = audioconvert/libspa-audioconvert

    In this example, we instruct wireplumber to only any api.alsa.* factory name from the libspa-alsa library, and also any audio.convert.* factory name from the libspa-audioconvert library.

  • context.modules

    Used to load PipeWire modules. This does not affect the PipeWire daemon by any means. It exists simply to allow loading libpipewire modules in the PipeWire core that runs inside WirePlumber. This is usually useful to load PipeWire protocol extensions, so that you can export custom objects to PipeWire and other clients.

    Users can also pass key-value pairs if the specific module has arguments, and a combination of 2 flags: ifexists flag is given, the module is ignored when not found; if nofail is given, module initialization failures are ignored:

      name = <module-name>
      [ args = { <key> = <value> ... } ]
      [ flags = [ [ ifexists ] [ nofail ] ]


    context.modules = [
      { name = libpipewire-module-adapter }
        name = libpipewire-module-metadata,
        flags = [ ifexists ]

    The above example loads both PipeWire adapter and metadata modules. The metadata module will be ignored if not found because of its ifexists flag.

  • context.components

    Used to load WirePlumber components. Components can be either WirePlumber modules written in C, WirePlumber scripts or other configuration files:

    { name = <component-name>, type = <component-type> }

    Valid component types include:

    • module: A WirePlumber shared object module

    • script/lua: A WirePlumber Lua script (requires libwireplumber-module-lua-scripting)

    • config/lua: A WirePlumber Lua configuration file (requires libwireplumber-module-lua-scripting)


    context.components = [
      { name = libwireplumber-module-lua-scripting, type = module }
      { name = main.lua, type = config/lua }

    This will load the WirePlumber lua-scripting module, dynamically, and then it will also load any components specified in the main.lua file.


    When loading lua configuration files, WirePlumber will also look for additional files in the directory suffixed with .d and will load all of them as well. For example, loading example.lua will also load any .lua files under example.lua.d/. In addition, the presence of the main file is optional, so it is valid to specify example.lua in the component name, while example.lua doesn’t exist, but example.lua.d/ exists instead and has .lua files to load.

    For more information about lua configuration files, see the Lua configuration files section.