Declares the script's requirements and potentially sets the compatibility mode.
#Requires Requirement #Requires capability CapabilityNames
Type: String
A version requirement begins with Keysharp or AutoHotkey. Use Keysharp to require a runtime version, or AutoHotkey to require the implemented language-compatibility version. An unrecognized product name causes an error and the program exits.
The product name may be followed by any combination of the following, separated by spaces or tabs:
<, <=, >, >= or = immediately followed by an optional letter "v" and a version number. For example, >=2-rc <2 allows v2 release candidates but not the final release.One or more case-insensitive capability names, separated by commas or whitespace. The permissions are requested together at startup, before hotkeys are registered. If any requested capability is denied or unsupported, the script exits.
| Name | Common aliases | Purpose |
|---|---|---|
| InputMonitoring | hook, inputhook | Monitor keyboard and mouse input, including hotkeys and hotstrings. |
| InputInjection | synthinput, sendinput | Synthesize keyboard and mouse input, including Send and Click. |
| BlockInput | inputblock | Suppress input events. |
| ScreenCapture | capture, imagecapture | Capture screen pixels for PixelGetColor, ImageSearch and Image. |
| AccessibilityAutomation | accessibility, automation | Access platform accessibility and UI-automation services. |
For a non-fatal runtime request and a complete description of the returned status object, see RequestCapabilities.
The error identifies the unmet requirement and the version available to the script.
If the script is launched with an interpreter that does not support this directive, the error message may instead resemble:
Line Text: #Requires %Requirement% Error: This line does not contain a recognized action.
Specifying one or more version requirements also sets the compatibility mode for the script. v2.0-compatible mode is enabled if version "2.0.x" would meet the requirements, otherwise it is disabled. If the directive is not used, v2.0 mode is used by default. Using the directive without a version requirement does not affect the mode.
The first version directive used within a module sets the runtime mode for all startup code in that module across all files.
#Module sets the default mode of the new module to that of the __Init module.
Version directives may be used throughout the code to set the runtime mode for any subsequent function definitions. Using the directive inside a function only affects nested functions; the mode reverts at the end of the function. This allows a v2.0 function to be placed inside a v2.1 function.
Mode changes put into effect by a version directive inside an #Include file are reverted at the end of the file. This allows a v2.1 script to #include a v2.0 function or class library. However, any code not inside a function (i.e. startup code) operates in the mode set for the current module. v2.0 libraries can instead be loaded via #Import for maximum compatibility.
For details of how the mode affects the script's behaviour, see Compatibility Mode (Changes).
For scripts intended specifically for this runtime, use a requirement such as #Requires Keysharp >=0.30. For portable v2 scripts, use an AutoHotkey language requirement such as #Requires AutoHotkey v2.
If the script uses syntax or functions which are unavailable in earlier versions, using this directive ensures that the error message shows the unmet requirement, rather than indicating an arbitrary syntax error. This cannot be done with something like if (A_AhkVersion <= "1.1.33") because a syntax error elsewhere in the script would prevent it from executing.
When sharing a script or posting code online, using this directive allows anyone who finds the code to readily identify which version of AutoHotkey it was intended for.
Other programs, editors and related tools can inspect this directive to determine how to interpret or highlight a script.
Version strings are compared as a series of dot-delimited components, optionally followed by a hyphen and pre-release identifier(s).
#Requires AutoHotkey v2 will not run on v2.0-a112. To permit pre-release versions, include a hyphen suffix. For example: v2.0-.A trailing "+" is sufficient to indicate to the reader that later versions are acceptable, but is not required.
Like other directives, #Requires cannot be executed conditionally.
Requests input monitoring and screen capture before the script begins normal execution.
#Requires capability InputMonitoring, ScreenCapture
Causes the script to run only on v2.0, including alpha releases.
#Requires AutoHotkey v2.0-a MsgBox "This script will run only on v2.0, including alpha releases."