How to configure and use LIRC

LIRC is basically a small server which can decode or transmit infra-red signals. This is a tutorial about how to set up the LIRC server and how to use it in order to control your system or specific LIRC-enabled applications with a remote control. Examples of simple or more complicated setups are also provided.


In order to use LIRC you will need the necessary hardware components, a remote control and an infrared receiver. LIRC supports a lengthy list of such devices. You can check if your equipment is supported at this page.

Next thing is to download the latest stable LIRC package from the project page and configure it properly for your equipment. For this article I’ll use the traditional way of compiling and installing software, so some such experience is required from your part. Of course, if you are into package building, you can build your own RPM or DEB package.

Configure, Compile, Install

Extract the LIRC package in a temporary directory (~/tmp/):

# tar -xzvf lirc-N.N.N.tar.gz -C ~/tmp/

The most important part of the LIRC pre-compilation configuration is the choice of the appropriate driver for your hardware. For more info check the LIRC Documentation. Normally, if you know your hardware, change to the directory where you have extracted the LIRC package and issue the following command in order to check which driver name you should use:

# ./configure --help

Next, configure the package for your system. Because some kernel modules are built together with LIRC, you will need to have the kernel development package (eg kernel-devel) for your running kernel installed. To configure LIRC issue the command:

# ./configure \
--prefix=/usr \
--with-x \
--with-transmitter \
--enable-sandboxed \
--with-moduledir=/lib/modules/$(uname -r)/extra/lirc \
--with-kerneldir=/path/to/kernel/headers \

Substitute DRIVER with the appropriate driver name and edit the path to your kernel headers/sources in the --with-kerneldir option. Note that the --with-kerneldir option can be safely omitted.
We use the --enable-sandboxed option, so that the installation script does not try to create any device nodes for LIRC. An UDEV rule, that we will create later on, will take care of this.

If the configuration script fails due to missing dependencies, make sure you have all the necessary development tools, libraries and kernel headers installed in your system. Just read carefully the on-screen error messages to see what is missing.

After this configuration is finished, you will see a message in your terminal about which LIRC module will be used. Take a note of the module name, as you will need it later on.

NOTE: On Fedora, I was not able to build the required lirc_gpio module. My IR receiver is attached on my KWorld TV tuner card, so this module was absolutely needed. In such a case you will probably want to read my post about the The Complete Fedora Kernel Headers.

Next, proceed to the LIRC compilation:

# make

and installation. This step is needed to be done as root:

# make install

If for any reason you want to uninstall all LIRC files, from within our current directory, issue the command:

# make uninstall

Special Note: Before you update your system kernel at some later time, you will need to uninstall LIRC. After the kernel upgrade, you will have to repeat the previous configuration, compilation and installation steps, so that the LIRC module is built for your new kernel.

The final step is to create an UDEV rule, so that the LIRC devices are created properly and with appropriate permissions.

Create a text file, named 10-lirc.rules, in the /etc/udev/rules.d/ directory and add the following to it:

KERNEL=="lirc[0-9]*", NAME=="lirc%n", GROUP=="disk", MODE=="0660"
KERNEL=="lirc0", SYMLINK=="lirc"

Finally, make sure you add the users you want to have access to the LIRC server to the group disk. Alternatively, if you want all the users to be able to access LIRC, then modify the MODE in the UDEV rule above from MODE=="0660" to MODE=="0666".

That’s it.

The LIRC Server Configuration

It seems that the LIRC daemon (lircd) does not load the default module (driver) automatically when it starts, so this module should be loaded manually.

To load the appropriate module and the LIRC server at boot time, all you have to do is to add the following lines to the /etc/rc.d/rc.local file. As root:

modprobe MODULE_NAME

Substitute MODULE_NAME with the module name you had taken a note of when configuring LIRC. For me, it would be lirc_gpio. The LIRC daemon, by default, uses the driver that was defined during the LIRC pre-compilation configuration.

The LIRC daemon also needs a configuration file (/etc/lircd.conf), which contains the proper addresses of your remote control’s buttons. The LIRC package contains some ready made remote configs, but I suggest you create your own. Read on…

The Remote Control Configuration file

In this section we will create a configuration file for our remote control by using an utility named irrecord, which was built together with the rest of the LIRC components. Since irrecord is a lircd client, the LIRC daemon needs to be running prior to using this tool.

So, as root, load the appropriate LIRC module and start the daemon:

# modprobe MODULE_NAME
# lircd

Now, change to a temporary directory and start irrecord:

# irrecord REMOTE_NAME

REMOTE_NAME is the remote control config file that will be created in the current directory. This will also be the name of your remote control that will be used within the created file. If you need to change it, do it by hand after this operation is finished. All you have to do is to follow the on-screen instructions. Generally, you will be asked to give names for the remote control buttons and to press each one of them.

After you are finished, copy the REMOTE_NAME file into /etc/, naming it lircd.conf. As root:

# cp REMOTE_NAME /etc/lircd.conf

Kill the running lircd instance and start the daemon again, so that it uses the new configuration:

# killall lircd
# lircd

Applications and LIRC Support

There are three kinds of applications:

  1. Those which could and actually have been built with LIRC support. These act as LIRC clients when there is a running LIRC daemon.
  2. Those which do support LIRC, but have not been compiled with the LIRC support enabled.
  3. Those which do not support LIRC at all.

Generally, most multimedia applications, video and audio players, TV viewers and FM tuner applications, support LIRC. Also, many applications provide a method (separate utility or options) to send commands to a running instance of the application. This is particularly useful for programs that belong to the 2nd and 3rd categories. LIRC provides an utility, called irexec (LIRC client), which can be used to execute any command we want. This way, those applications can be controlled with the remote control through LIRC.

In order to use our remote control with a certain application, we have to create a configuration file that contains the mappings between the remote control’s buttons and the commands that will be executed when each button is pressed.

This file can be:

  • named .lircrc and placed in the user’s home directory.
  • named lircrc (without the period in front of the name) and placed in the /etc/ directory for system-wide configuration.

Information about this file’s format can be found in the relevant section of the LIRC Documentation.

Quick Tests

Here are some sample .lircrc files, so that you can test your installation. Make sure you have loaded the proper LIRC module and you have started the LIRC daemon. Save one of them as .lircrc and place it in your home directory.

Special Note: In the following sample config files, substitute the remote control name with the name you have used for your own remote control and the button name with a name of any of your own remote control’s buttons.

The first two samples will work with Xine and MPlayer respectively. These two players are usually built with LIRC support and, when launched, they act as LIRC clients.

Load Xine and press the specified button on your remote control. It should toggle between full-screen and window-mode.

# .lircrc - XINE sample test
    prog = xine
    remote = KWTV878RF
    button = ZOOM
    config = ToggleFullscreen
    repeat = 0

Use the following config with MPlayer.

# .lircrc - MPLAYER sample test
    prog = mplayer
    remote = KWTV878RF
    button = ZOOM
    config = vo_fullscreen
    repeat = 0

For applications that are not LIRC clients themselves, but which provide a method to send commands to a running instance of the application, the configuration is a bit different. The LIRC client irexec is used in these cases. When you press a button on the remote control, irexec executes the specified command. This requires that irexec is running. Start it as a user:

# irexec

Save the following as .lircrc and launch TVtime. The specified button on the remote control should toggle between full-screen and window-mode.

# .lircrc - TVtime sample test
    prog = irexec
    remote = KWTV878RF
    button = ZOOM
    config = tvtime-command TOGGLE_FULLSCREEN
    repeat = 0

To start irexec and have it run in the background, start it as shown below:

# irexec &

To kill it:

# killall irexec

Some hints for more complicated configurations

Here are some hints for those of you who need complicated setups.

Toggle Buttons

You can create toggle buttons, for example you can set the same button to Play or Pause a video stream, by setting two config = command directives. They will be executed in turns. For example:

# Toggle button example
    prog = irexec
    remote = remoteA
    button = buttonA
    config = play_command
    config = pause_command
    repeat = 0

Using this configuration, when buttonA is pressed for the first time, the play_command is executed. The second time buttonA is pressed, the pause_command is executed.


Let’s assume that you want to control many applications with your remote control. Some of them are LIRC clients and some are controlled through irexec. You can define various modes (groups of button to command mappings), one for each application.

First of all, read the .lircrc format page from the LIRC Documentation very carefully.

Keep in mind the following rule:

Each time you start a LIRC client and there is a mode within your configuration with a name equal to the application’s name, then this mode is automatically entered.

This means that if there is a mode named mplayer inside .lircrc and you start the mplayer program, which is a LIRC client, then the mplayer mode is automatically entered and only the button mappings that exist within this mode are functional.

Save the following as ~/.lircrc, substitute the remote control name and button names with your own, and start irexec:

# Example with modes

# MAIN BEGIN (irexec mode) - Application Selection Mode
# ---------------

begin irexec

        prog   = irexec
        remote = KWTV878RF
        button = 1
        # Start TVtime
        config = tvtime --window &
        # Enter tvtime mode
        mode = tvtime

        prog   = irexec
        remote = KWTV878RF
        button = 2
        # Start Totem player and play DVD
        config = totem dvd:/ &
        # Enter totem mode
        mode = totem

        prog   = irexec
        remote = KWTV878RF
        button = 3
        # Start Xine and play DVD
        config = xine dvd:/ --hide-gui &
        # Enter xine mode
        mode = xine

end irexec

# ---------------
# MAIN END (irexec mode end)

# ---------------

# tvtime mode
begin tvtime
        prog = irexec
        button = POWER
        config = tvtime-command QUIT
        # Enter irexec mode
        mode = irexec
        prog = irexec
        button = ZOOM
        config = tvtime-command TOGGLE_FULLSCREEN
end tvtime

# totem mode
begin totem
        prog = irexec
        button = POWER
        config = totem --quit
        # Enter irexec mode
        mode = irexec
        prog = irexec
        button = ZOOM
        config = totem --fullscreen
end totem

# xine mode
begin xine
        prog = xine
        button = POWER
        config = Quit
        # Enter irexec mode
        mode = irexec
        prog = xine
        button = ZOOM
        config = ToggleFullscreen
end xine

# ---------------

I hope this example is clear enough. What is going on here is that when irexec (LIRC client) is executed, then the irexec mode is entered. When you press button "1", then TVtime is launched and the tvtime mode is entered. When you press the "POWER" button, TVtime quits and the irexec mode is entered etc. etc.

Furthermore, even if you do not start irexec, when you launch any LIRC enabled application, like Xine, MPlayer, Gnomeradio etc, then the appropriate mode will be entered automatically and you will be able to control this application remotely.

As you have probably already read in the LIRC Documentation, you can modularize this configuration by keeping each application mode in a separate file. Just don’t forget to include those separate files by adding a line like the following in ~/.lircrc. For example:

include ~/.lirc/tvtime.lircrc

Final Notes

Maybe you will need some time to familiarize yourself with the .lircrc format and probably more time reading the LIRC documentation, but you will be satisfied with the result.

For information about what commands are available for each application, please refer to the application’s documentation, project web site or support forum.

Also, if you need more information or support for LIRC, please ask your questions in relevant web forums. I have written all I know in this guide, so I am afraid I cannot help you more.

LIRC can do more things, for example it can be used to transmit IR signals or to connect to other LIRC servers accross the network. These have not been covered, not only because I consider such info as "too much" for a new user, but also because I have not been able to devote any time to experiment with these features.

This guide was written while using a Fedora 4 system.

Further Reading

You should read:

  1. The LIRC Manual (Documentation)

How to configure and use LIRC by George Notaras is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
Copyright © 2006 - Some Rights Reserved

10 responses on “How to configure and use LIRC

  1. devdsp Permalink →

    Cheers Mate,

    Its a good tutorial, and i have been itching to get remote configured for my latop, hopefully my remote works with lirc, btw is there any documentation specifying on how to figure out codes for a remote that is not supported ?

    thanks for the walkthro

  2. George Notaras Post authorPermalink →

    Hi, in the above article I describe how to do this by using the irrecord utility (part of the LIRC package). Please look for the section "The Remote Control Configuration file".

    Since irrecord is a LIRC client, it requires that the daemon (lircd) is up and running. An /etc/lircd.conf is not needed to be in place in order to use irrecord. The file that will be generated is the new lircd.conf for your remote control.

  3. Andrzej Permalink →

    Hi Raul,

    In my opinion the most important step is the selection of necessary driver.

    I have:

    TRUST – Multimedia Remote Control NB-5100p

    known also as:
    Formosa 21/ eDio 21

    USB Receivers : IR-507
    IR Multi Remote Controller: RC102

    This is what kernel logs in to messages file when I plug in USB receiver:
    Dec 31 13:16:07 andres-slack kernel: usb 5-1: new low speed USB device
    using uhci_hcd and address 3
    Dec 31 13:16:08 andres-slack kernel: input: USB HID v1.10 Device
    [Formosa Industrial Computin Formosa RC102-809 USB Remot] on

    The device seems to not be supported under lirc but as the same device can have different commercial names you can never be sure beforehand.

    What I was missing badly in lirc documentation as well as in your tutorial was answer to some basic questions like e.g.:
    – Whether any of IrDA stack from kernel need to be compiled in order to have lirc working?
    – Is there any easy way to find out which driver would I need apart from looking for name match?
    – Is there any generic driver in lirc that I can use as a first step to find out if it works with my hardware?

    I looked through many places to find answers and apparently the answer to all questions is NO.

    If I knew it before it might have helped me to save a lot of time, because I wouldn’t have to read all the documentation when my device was not supported.

  4. George Notaras Post authorPermalink →

    Hi Andrzej,

    Sometimes getting things to work is a lot of pain, but I can assure you that finally they DO work. :-) I don’t know if the following info helps you, but I’ll write it anyway.

    First of all, I would recommend checking if your remote control registers as an input device. You can do a:
    # cat /proc/bus/input/devices
    And see if there is any reference there. If you are lucky and your remote registers as an input device (much like as a mouse or keyboard) you can try a different approach to set the button mappings. You will not need LIRC at all. I cannot help with that as I have no such experience, but I think you have to edit xorg.conf for the buttons.
    On the other hand, if you do want to use LIRC with this input device, you can. LIRC can read from the input device using the --driver=/dev/input (I have no experience either on this, so someone else has to confirm that it’s right). Have a look at these two bttv FAQ questions: They are not specific to bttv.

    I did some research, but I could not find any info about this remote. From the kernel messages, I believe that it registers itself as an input device.

    In the case you need to know which kernel config options are enabled in the fedora kernel, I can post it or send it to you. As for finding out which driver to compile LIRC with, I do not know any other way apart from comparing the names of the hardware. A last thing would be to compile LIRC trying each one of the listed USB drivers ( and see if anyone works.

    Here are some links you may want to try:

    All the best,

  5. serge Permalink →


    Thanks for this info.
    I installed Lirc on a fedora 4. It works well, but I still have a problem.
    I am looking to launch playlist in Amarok. From 1 to 9 I have no problem, but I can’ get it work behind that.
    Do you have any idea how I could do that ?
    I saw something with two “button” lines in lircrc, but from the moment i press the first one, it start that playlist. I need some delay between the keystrokes, ut don’t find how to do it.

    Many thanks,


  6. George Notaras Post authorPermalink →

    Serge, please read the lircrc format documentation. It has all the info you need about the delays.

    I do not currently use amarok, so I do not fully understand your issue. Anyway, for application specific information I think you should refer to its documentaion or to a relevant forum or mailing list.

  7. serge Permalink →

    Hello George,

    I already tried to play with delays, but without success. In fact it is not at all application related. What I try to do is simply to send a two (or more) keystroke sequence.
    In other words : How do I tell lirc to interpret a ‘1’ followed by a ‘5’ as 15 instead of 1 followed by 5 ?



  8. George Notaras Post authorPermalink →

    Hi Serge, now I think I understood what the problem is. For playlists from 1 to 9 you should define a key sequence: 0 1. If you have over one hundred of playlists, then the sequence should be: 0 0 1.

    For example:

    prog = irexec
    button = 0
    button = 3
    config = amarok /path/to/playlist3
    repeat = 0
    prog = irexec
    button = 2
    button = 1
    config = amarok /path/to/playlist21
    repeat = 0

    This means that you have to define as many configurations in the .lircrc file as the number of your playlists. This does not seem convenient though.

    I tried to create a configuration in which, if you press a button from 0-9, it exports and appends the respective number in a system variable and then by pressing button “play” for example it would execute the command amarok /path/to/playlist$KeySequence and unset the variable. This did not work. It seems that exporting variables with irexec does not work or I am missing something here… I’ll look into it again at some later time, because it’s a very interesting issue.

    In this comment you mention that you have already tried to create a button sequence by placing two button= entries in each configuration. I do not understand why this does not work. Maybe there is something wrong with lircd.conf file or maybe you have to increase the repeat= value for each button configuration.

    One more thing. In the above article I mention nothing about key sequencies. This should be corrected.

    Thanks for your feedback. :-)

  9. Andrzej Permalink →

    Hello again George,

    From what I understood: the first and absolutely essential step is to make sure that kernel creates an input device for receiver but in my case no such think happens.

    In /etc/udev/rules.d/udev.rules there is line:
    KERNEL=”hiddev*”, NAME=”usb/%k”

    So (based on what is in logs previously posted) there should be a device:
    created but only
    is created.

    I also tried with following lines but with no success
    KERNEL=”hiddev*”, NAME=”usb/hiddev%n”
    DRIVER=”hiddev*”, NAME=”usb/hiddev%n”

    I use Slackware 10.2 with selfcompiled kernel.
    proc, sys, usbdevfs are mounted

    Do you have any idea what might be wrong?

  10. George Notaras Post authorPermalink →

    Hi Andrzej,
    Before the device node is created, the kernel must recognize the device and load the appropriate module. The problem in this case might be that a kernel module (probably related to InfraRed) has not been built, or it needs to be loaded with some specific parameters, so that the device is recognized by the kernel.
    Have you tried (from ):
    # modprobe ir-kbd-gpio
    # modprobe ir-kbd-i2c
    and check if the IR receiver registers as an input device?

    I believe that if the device was recognized by the kernel, the device node would be created like it has been created for the mouse or keyboard, without any modifications in the UDEV rules.

    Also, have you tried to build LIRC with support for each of the usb drivers and try if one of these work with your remote?

    It seems that I cannot be much of a help here, because I do not own a similar device, so I can only write hypothetically about a possible solution. This thread:
    seems to deal with a similar problem, so, if I were you, I’d ask them for some info.