{
    "mode": "man",
    "parameter": "irqbalance",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/irqbalance/1/json",
    "generated": "2026-06-15T14:10:30Z",
    "synopsis": "",
    "sections": {
        "NAME": {
            "content": "irqbalance - distribute hardware interrupts across processors on a multiprocessor system\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "",
            "subsections": [
                {
                    "name": "irqbalance",
                    "content": ""
                }
            ]
        },
        "DESCRIPTION": {
            "content": "The  purpose of irqbalance is to distribute hardware interrupts across processors on a multi‐\nprocessor system in order to increase performance.\n\n",
            "subsections": []
        },
        "OPTIONS": {
            "content": "",
            "subsections": [
                {
                    "name": "-o, --oneshot",
                    "content": "Causes irqbalance to be run once, after which the daemon exits.\n\n",
                    "flag": "-o",
                    "long": "--oneshot"
                },
                {
                    "name": "-d, --debug",
                    "content": "Causes irqbalance to print extra debug information.  Implies --foreground.\n\n",
                    "flag": "-d",
                    "long": "--debug"
                },
                {
                    "name": "-f, --foreground",
                    "content": "Causes irqbalance to run in the foreground (without --debug).\n\n",
                    "flag": "-f",
                    "long": "--foreground"
                },
                {
                    "name": "-j, --journal",
                    "content": "Enables log output optimized for systemd-journal.\n\n",
                    "flag": "-j",
                    "long": "--journal"
                },
                {
                    "name": "-p, --powerthresh=<threshold>",
                    "content": "Set the threshold at which we attempt to move a CPU into powersave mode If  more  than\n<threshold>  CPUs  are  more  than  1 standard deviation below the average CPU softirq\nworkload, and no CPUs are more than 1 standard deviation above (and have more  than  1\nIRQ assigned to them), attempt to place 1 CPU in powersave mode.  In powersave mode, a\nCPU will not have any IRQs balanced to it, in an effort to prevent that CPU from  wak‐\ning up without need.\n\n",
                    "flag": "-p",
                    "long": "--powerthresh",
                    "arg": "<threshold>"
                },
                {
                    "name": "-i, --banirq=<irqnum>",
                    "content": "Add the specified IRQ to the set of banned IRQs. irqbalance will not affect the affin‐\nity of any IRQs on the banned list, allowing them to be specified manually.  This  op‐\ntion  is  additive and can be specified multiple times. For example to ban IRQs 43 and\n44 from balancing, use the following command line: irqbalance --banirq=43 --banirq=44\n\n",
                    "flag": "-i",
                    "long": "--banirq",
                    "arg": "<irqnum>"
                },
                {
                    "name": "-m, --banmod=<module",
                    "content": "Add the specified module to the set of banned modules, similar to  --banirq.   irqbal‐\nance  will  not  affect the affinity of any IRQs of given modules, allowing them to be\nspecified manually. This option is additive and can be specified multiple  times.  For\nexample to ban all IRQs of module foo and module bar from balancing, use the following\ncommand line: irqbalance --banmod=foo --banmod=bar\n\n",
                    "flag": "-m",
                    "long": "--banmod",
                    "arg": "<module"
                },
                {
                    "name": "-c, --deepestcache=<integer>",
                    "content": "This allows a user to specify the cache level at which irqbalance partitions cache do‐\nmains.   Specifying  a  deeper  cache  may  allow  a greater degree of flexibility for\nirqbalance to assign IRQ affinity to achieve greater performance increases,  but  set‐\nting  a cache depth too large on some systems (specifically where all CPUs on a system\nshare the deepest cache level), will cause irqbalance to see balancing as unnecessary.\nirqbalance --deepestcache=2\n\nThe default value for deepestcache is 2.\n\n",
                    "flag": "-c",
                    "long": "--deepestcache",
                    "arg": "<integer>"
                },
                {
                    "name": "-l, --policyscript=<script>",
                    "content": "When  specified, the referenced script or directory will execute once for each discov‐\nered IRQ, with the sysfs device path and IRQ number passed as  arguments.   Note  that\nthe  device  path  argument  will point to the parent directory from which the IRQ at‐\ntributes directory may be directly opened.  Policy scripts specified need to be  owned\nand executable by the user of irqbalance process, if a directory is specified, non-ex‐\necutable files will be skipped.  The script may specify zero or more  key=value  pairs\nthat will guide irqbalance in the management of that IRQ.  Key=value pairs are printed\nby the script on stdout and will be captured and interpreted by  irqbalance.   Irqbal‐\nance  expects  a zero exit code from the provided utility.  Recognized key=value pairs\nare:\n\nban=[true | false]\nDirects irqbalance to exclude the passed in IRQ from balancing.\n\nbalancelevel=[none | package | cache | core]\nThis allows a user to override the balance level of a given IRQ.  By default the  bal‐\nance  level  is  determined  automatically based on the pci device class of the device\nthat owns the IRQ.\n\nnumanode=<integer>\nThis allows a user to override the NUMA node that sysfs indicates a given  device  IRQ\nis  local  to.  Often, systems will not specify this information in ACPI, and as a re‐\nsult devices are considered equidistant from all NUMA nodes in a system.  This  option\nallows for that hardware provided information to be overridden, so that irqbalance can\nbias IRQ affinity for these devices toward its most local node.  Note that  specifying\na  -1  here forces irqbalance to consider an interrupt from a device to be equidistant\nfrom all nodes.\n\nNote that, if a directory is specified rather than a regular file, all files in\nthe directory will be considered policy scripts, and executed on adding of an irq to a\ndatabase.   If  such a directory is specified, scripts in the directory must addition‐\nally exit with one of the following exit codes:\n\n0      This indicates the script has a policy for the referenced irq, and that further script\nprocessing should stop\n\n1      This  indicates  that the script has no policy for the referenced irq, and that script\nprocessing should continue\n\n2      This indicates that an error has occurred in the script,  and  it  should  be  skipped\n(further processing to continue)\n\n",
                    "flag": "-l",
                    "long": "--policyscript",
                    "arg": "<script>"
                },
                {
                    "name": "-s, --pid=<file>",
                    "content": "Have  irqbalance write its process id to the specified file.  By default no pidfile is\nwritten.  The written pidfile is automatically unlinked when irqbalance exits.  It  is\nignored when used with --debug or --foreground.\n",
                    "flag": "-s",
                    "long": "--pid",
                    "arg": "<file>"
                },
                {
                    "name": "-t, --interval=<time>",
                    "content": "Set the measurement time for irqbalance.  irqbalance will sleep for <time> seconds be‐\ntween samples of the irq load on the system cpus. Defaults to 10.\n",
                    "flag": "-t",
                    "long": "--interval",
                    "arg": "<time>"
                }
            ]
        },
        "ENVIRONMENT VARIABLES": {
            "content": "IRQBALANCEONESHOT\nSame as --oneshot.\n\n\nIRQBALANCEDEBUG\nSame as --debug.\n\n\nIRQBALANCEBANNEDCPUS\nProvides a mask of CPUs which irqbalance should ignore and never assign interrupts to.\nIf  not specified, irqbalance use mask of isolated and adaptive-ticks CPUs on the sys‐\ntem as the default value.  This is a hexmask without the leading ’0x’. On systems with\nlarge  numbers  of  processors, each group of eight hex digits is separated by a comma\n’,’. i.e.  ‘export IRQBALANCEBANNEDCPUS=fc0‘ would prevent irqbalance from assigning\nirqs     to     the     7th-12th     cpus     (cpu6-cpu11)    or    ‘export    IRQBAL‐\nANCEBANNEDCPUS=ff000000,00000001‘ would prevent irqbalance from  assigning  irqs  to\nthe  1st  (cpu0)  and  57th-64th cpus (cpu56-cpu63).  Notes: This environment variable\nwill be discarded, please use IRQBALANCEBANNEDCPULIST instead. Before deleting  this\nenvironment variable, Introduce a deprecation period first for the consider of compat‐\nibility.\n\n\nIRQBALANCEBANNEDCPULIST\nProvides a cpulist which irqbalance should ignore and never assign interrupts to.   If\nnot  specified,  irqbalance use mask of isolated and adaptive-ticks CPUs on the system\nas the default value.\n\n",
            "subsections": []
        },
        "SIGNALS": {
            "content": "SIGHUP Forces a rescan of the available IRQs and system topology.\n\n",
            "subsections": []
        },
        "API": {
            "content": "irqbalance is able to communicate via socket and return  it's  current  assignment  tree  and\nsetup,  as  well as set new settings based on sent values. Socket is abstract, with a name in\nform of irqbalance<PID>.sock , where <PID> is the process ID of irqbalance instance to commu‐\nnicate with.  Possible values to send:\n\nstats  Retrieve  assignment  tree  of IRQs to CPUs, in recursive manner. For each CPU node in\ntree, it's type, number, load and whether the save mode is active are sent.  For  each\nassigned  IRQ  type, it's number, load, number of IRQs since last rebalancing and it's\nclass are sent. Refer to types.h file for explanation of defines.\n\nsetup  Get the current value of sleep interval, mask of banned CPUs and list of banned IRQs.\n",
            "subsections": [
                {
                    "name": "settings sleep <s>",
                    "content": "Set new value of sleep interval, <s> >= 1.\n\nsettings cpus <cpunumber1> <cpunumber2> ...\nBan listed CPUs from IRQ handling, all old values of banned CPUs are forgotten.\n"
                },
                {
                    "name": "settings ban irqs <irq1> <irq2> ...",
                    "content": "Ban listed IRQs from being balanced, all old values of banned IRQs are forgotten.\n\nirqbalance checks SCMCREDENTIALS of sender (only root user is allowed to  interact).   Based\non chosen tools, ancillary message with credentials needs to be sent with request.\n\n"
                }
            ]
        },
        "HOMEPAGE": {
            "content": "https://github.com/Irqbalance/irqbalance\n\n\n\n\nLinux                                         Dec 2006                                 IRQBALANCE(1)",
            "subsections": []
        }
    },
    "summary": "irqbalance - distribute hardware interrupts across processors on a multiprocessor system",
    "flags": [
        {
            "flag": "-o",
            "long": "--oneshot",
            "arg": null,
            "description": "Causes irqbalance to be run once, after which the daemon exits."
        },
        {
            "flag": "-d",
            "long": "--debug",
            "arg": null,
            "description": "Causes irqbalance to print extra debug information. Implies --foreground."
        },
        {
            "flag": "-f",
            "long": "--foreground",
            "arg": null,
            "description": "Causes irqbalance to run in the foreground (without --debug)."
        },
        {
            "flag": "-j",
            "long": "--journal",
            "arg": null,
            "description": "Enables log output optimized for systemd-journal."
        },
        {
            "flag": "-p",
            "long": "--powerthresh",
            "arg": "<threshold>",
            "description": "Set the threshold at which we attempt to move a CPU into powersave mode If more than <threshold> CPUs are more than 1 standard deviation below the average CPU softirq workload, and no CPUs are more than 1 standard deviation above (and have more than 1 IRQ assigned to them), attempt to place 1 CPU in powersave mode. In powersave mode, a CPU will not have any IRQs balanced to it, in an effort to prevent that CPU from wak‐ ing up without need."
        },
        {
            "flag": "-i",
            "long": "--banirq",
            "arg": "<irqnum>",
            "description": "Add the specified IRQ to the set of banned IRQs. irqbalance will not affect the affin‐ ity of any IRQs on the banned list, allowing them to be specified manually. This op‐ tion is additive and can be specified multiple times. For example to ban IRQs 43 and 44 from balancing, use the following command line: irqbalance --banirq=43 --banirq=44"
        },
        {
            "flag": "-m",
            "long": "--banmod",
            "arg": "<module",
            "description": "Add the specified module to the set of banned modules, similar to --banirq. irqbal‐ ance will not affect the affinity of any IRQs of given modules, allowing them to be specified manually. This option is additive and can be specified multiple times. For example to ban all IRQs of module foo and module bar from balancing, use the following command line: irqbalance --banmod=foo --banmod=bar"
        },
        {
            "flag": "-c",
            "long": "--deepestcache",
            "arg": "<integer>",
            "description": "This allows a user to specify the cache level at which irqbalance partitions cache do‐ mains. Specifying a deeper cache may allow a greater degree of flexibility for irqbalance to assign IRQ affinity to achieve greater performance increases, but set‐ ting a cache depth too large on some systems (specifically where all CPUs on a system share the deepest cache level), will cause irqbalance to see balancing as unnecessary. irqbalance --deepestcache=2 The default value for deepestcache is 2."
        },
        {
            "flag": "-l",
            "long": "--policyscript",
            "arg": "<script>",
            "description": "When specified, the referenced script or directory will execute once for each discov‐ ered IRQ, with the sysfs device path and IRQ number passed as arguments. Note that the device path argument will point to the parent directory from which the IRQ at‐ tributes directory may be directly opened. Policy scripts specified need to be owned and executable by the user of irqbalance process, if a directory is specified, non-ex‐ ecutable files will be skipped. The script may specify zero or more key=value pairs that will guide irqbalance in the management of that IRQ. Key=value pairs are printed by the script on stdout and will be captured and interpreted by irqbalance. Irqbal‐ ance expects a zero exit code from the provided utility. Recognized key=value pairs are: ban=[true | false] Directs irqbalance to exclude the passed in IRQ from balancing. balancelevel=[none | package | cache | core] This allows a user to override the balance level of a given IRQ. By default the bal‐ ance level is determined automatically based on the pci device class of the device that owns the IRQ. numanode=<integer> This allows a user to override the NUMA node that sysfs indicates a given device IRQ is local to. Often, systems will not specify this information in ACPI, and as a re‐ sult devices are considered equidistant from all NUMA nodes in a system. This option allows for that hardware provided information to be overridden, so that irqbalance can bias IRQ affinity for these devices toward its most local node. Note that specifying a -1 here forces irqbalance to consider an interrupt from a device to be equidistant from all nodes. Note that, if a directory is specified rather than a regular file, all files in the directory will be considered policy scripts, and executed on adding of an irq to a database. If such a directory is specified, scripts in the directory must addition‐ ally exit with one of the following exit codes: 0 This indicates the script has a policy for the referenced irq, and that further script processing should stop 1 This indicates that the script has no policy for the referenced irq, and that script processing should continue 2 This indicates that an error has occurred in the script, and it should be skipped (further processing to continue)"
        },
        {
            "flag": "-s",
            "long": "--pid",
            "arg": "<file>",
            "description": "Have irqbalance write its process id to the specified file. By default no pidfile is written. The written pidfile is automatically unlinked when irqbalance exits. It is ignored when used with --debug or --foreground."
        },
        {
            "flag": "-t",
            "long": "--interval",
            "arg": "<time>",
            "description": "Set the measurement time for irqbalance. irqbalance will sleep for <time> seconds be‐ tween samples of the irq load on the system cpus. Defaults to 10."
        }
    ],
    "examples": [],
    "see_also": []
}