AHK-v2-script-converter: migrating AutoHotkey v1 scripts to v2
AHK v1 -> v2 script converter
At a glance
- What is it?
- Despite its name, this tool is an assistant rather than a converter. It rewrites AutoHotkey v1 syntax into v2, covers about eighty percent of the conversion automatically, and marks what it cannot handle with inspection comments rather than inventing code, and the Gui handling has four modes because the v1 window syntax has no single correct translation.
- Who is it for?
- AHK-v2-script-converter suits a script author with a large v1 codebase who wants the mechanical bulk of the migration done consistently and wants to be told, in the output, which parts still need a human. It is the wrong tool for a script that must convert perfectly unattended, since the README is explicit that manual edits should be expected and that the tool may not produce fully functional v2 code.
- Can I use it commercially?
- Yes. Unlicense is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 42 days ago.
- What is it written in?
- Mainly AutoHotkey, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 22, 2026, and from our analysis. They are not legal advice.
Editorial analysis
What the tool is and what it is not
The README opens by correcting the name. Despite its name, this converter functions more like an assistant for migrating scripts from AHK v1 to AHK v2 syntax.
The scope is stated in the same paragraph. It is designed to automate the most tedious parts of the conversion process, but its scope is limited. While the tool may occasionally produce fully functional v2 code, users should expect to make manual edits afterwards.
That framing is the honest description of what a source-to-source rewriter for a scripting language can be. AutoHotkey v2 was not a small syntax update, it changed the object model, the expression evaluation and the way windows and controls are addressed, so a mechanical translation of a large v1 script is a long tail of cases rather than a solved problem.
The recommended process is five steps. Open the converter UI, set the Gui conversion mode with dynamic recommended, press one of the three conversion buttons, expect the tool to cover about 80 percent or more of the conversion process automatically, then follow the post conversion guidelines for the remaining 20 percent as necessary.
The primary language is AutoHotkey, the licence field says Unlicense, which is a public domain dedication, and the homepage is a thread on the AutoHotkey forums. The last push was on 2026-09-12, with the recent releases being v2.0 from 2026-04-18, v1.8 from 2025-10-23 and v1.7.1 from 2025-06-24.
The four Gui conversion modes
The Gui handling is where the tool's design shows, because v1 window syntax has no single correct v2 translation and the tool offers four strategies for it.
The ORIGINAL mode provides Gui conversion using the original method, and the README notes it is being replaced by the updated modes. The SIMPLE mode is described as an updated version of the original mode, providing a similar but improved result, and is recommended for converting simple non-dynamic v1 Gui syntax.
The DYNAMIC mode is marked as recommended. It provides the best Gui conversion results, with limited support for dynamic attributes such as those within loops, function parameters, multiple scopes and ClassNN names. The trade-off is stated plainly: the v2 syntax is much different than the other modes, and it requires an include file before or after conversion.
The AUTO mode analyzes the v1 source code and selects the best mode automatically, either Simple or Dynamic.
The practical consequence is that the choice is not cosmetic. Dynamic produces a different shape of v2 code that needs an include file to work, so a script you convert in Dynamic mode is not directly comparable with one converted in Simple mode, and Auto can pick differently for different scripts. The README also mentions that the user can define the default GuiName and control prefix for v2 variable names, which matters because the v2 naming rules produce long generated identifiers otherwise.
The tool also flags an intention it has not yet delivered. The HK tab will eventually provide hotkey filtering to improve conversion performance, which is a hint that hotkey-heavy scripts are currently the slow case.
The three ways to run it
There are three entry points and they serve different purposes.
The GUI is the primary path. You download the full repo as a zip, then run the included Converter_UI.ahk script with AHK v2. The UI has tabs, and the TAB1 tab saves all settings from the other tabs, with auto-save recommended. The GUI tab provides several modes for Gui and GuiControl conversion, and the GENERAL tab holds the general conversion settings.
The script file path runs v2converter.ahk. You choose your input scriptfile.ahk written for AHK v1, and the converted script is named scriptfile_newV2.ahk in the same directory. You can also run v2converter.ahk -h in cmd to use the command line interface. After conversion you look over the visual diff to inspect the changes, and the repository has a diff/ directory alongside the convert/ directory.
The fragment path is QuickConvertorV2.ahk, for pasting v1 code. You can select a string in another program and press XButton1 to convert it, or paste it into the first edit pane and press the convert button, which is the orange arrow. When the cursor is on a function in the edit field, pressing F1 searches that function in the documentation, which is a small but genuinely useful integration. Play buttons let you run and close both the v1 and the v2 code, and compare buttons show the difference between the scripts.
There is a third mode on the GUI itself. The Run QC Unit Tests button runs QuickConvertorV2 in Unit-Test Mode for project contributors, and shift-clicking it shows the failed unit tests as well.
Why the tool argues for itself against AI
The README has a section titled Tool vs AI, and it is the clearest statement of what this kind of project is for.
For the tool, the argument is fast and consistent output, since it has been pre-tested for the common things it supports. And, more importantly, inspection comments are added for things it does not support, so it will not invent invalid code on the fly.
For AI, the listed weaknesses are token limits on lengthy scripts, semantic and context drift with lengthy scripts, the risk of providing invalid code through hallucinations, of removing code, or of changing logic flow, and that revision exchanges with AI can be time-consuming and may lead to compounded hallucinations.
This is a reasonable argument, and it is narrower than it first appears. The claim is not that an AI cannot convert AHK v1, it is that a deterministic rewriter with a test suite gives you the same result every time, and that the failure mode is a comment rather than a plausible-looking wrong line. For a script where a wrong line means a hotkey that fires the wrong thing, that difference is worth more than the convenience of a chat window.
The reference to the unit test mode fits this. There is a tests/ directory in the repository and a ConvertFuncs.ahk file, and the README describes a TestMode setting in the Gui Menu Settings where all the confirmed tests are checked to see whether the result stays the same, and where tests can also be saved easily.
What to do after the conversion runs
The post conversion section is the part of the README that a user should read before starting, because it calibrates expectations.
The first point is that the tool is limited and may not produce fully functional v2 code, that manual edits to the output should be expected, and that the tips in the debugging section should be used. The known limitations page is listed first as the thing to check.
The AHK documentation should be used when converting code, specifically the v2 changes page. The README also says that line comments are added to the v2 output, prefixed with a marker, and that they provide assistance for debugging. That is the mechanism that makes the tool honest: every place the converter was unsure is visible in the output as a comment rather than silently dropped.
After that there is a sequence of escalating options. A discussions page lists common conversion issues and potential fixes. Issues reported by others may provide fixes. If the problem is not there, create a new issue. And finally, ask for help, on the discussions page, on the AutoHotkey forums, or using a favourite AI tool.
That last option is worth noting, because it contradicts the Tool vs AI framing slightly. The tool is presented as the better converter, and then the last resort for a hard case is to bring in an AI tool. The two are not in competition so much as in sequence, which is probably the honest picture.
One practical note at the end of the README. You may still have the AutoHotkey v1 binary associated with .ahk files, and the converter is written in v2, so you need to either update AutoHotkey or open the repository in a command prompt and run the v2 executable against the script by name.
Where this tool is the wrong choice
The first limitation is stated by the project itself. The tool is limited and may not produce fully functional v2 code, and manual edits to the output should be expected. For a script you intend to run unattended afterwards, that is a disqualification.
The second is the GUI conversion, where even the recommended mode has limited support for dynamic attributes within loops, function parameters, multiple scopes and ClassNN names. A script that builds its windows dynamically, which is common in the v1 era, is exactly the case the tool handles worst, and the recommended Dynamic mode needs an include file that you have to source separately.
The third is variable name conflicts, which the README lists first among the known limitations and describes as very common and requiring manual attention. AHK v2 changed how variables are declared, so a converted script can easily end up with two identifiers that the v1 author would have assumed were distinct.
The fourth is the input method. The quick convert path depends on the XButton1 mouse button, which is a side button that many keyboards and mice do not have, so the fragment workflow has a hardware dependency that the paste path does not.
The fifth is the environment. Everything here runs inside AutoHotkey v2, which means the tool cannot be run on a machine that only has v1 installed without taking the extra step the README describes. And the project is a single-maintainer effort with release tags spaced months apart, so a bug you hit may sit unfixed for a while.
How it compares with the official v2 migration advice and with an LLM
The comparison with the official v2 migration route is the first one, and it is not a fair fight because they do different jobs. The AutoHotkey documentation's v2 changes page is a specification, and it is what the README tells you to consult when the tool leaves you with a question. The tool is a mechanical first pass that saves you from typing out the hundreds of small syntax changes a large script contains. A specification cannot do that, and the tool cannot answer the question the specification answers.
The comparison with a large language model is the one the README argues directly, and the interesting part is the axis of difference. Both approaches read v1 and write v2. The tool is deterministic, tested and marks its gaps; a model is generative, adaptive and can handle a case no rule covers, at the risk of producing plausible code that is wrong in a way you may not notice.
For a large script the model's weaknesses compound. Context drifts across thousands of lines, a hallucinated line is syntactically valid so nothing complains, and a revision conversation can accumulate errors. The tool's weaknesses are different and more visible: it stops and says so.
There is a third option that neither argument mentions much, which is a hybrid. Run the tool for the bulk, then use a model on the specific fragments the tool flagged, where the context is small enough for the model to be reliable. That is close to what the README's escalation list describes at the end, where asking an AI tool is the final step.
The fourth comparison is with the other route entirely, which is to leave v1 alone. AHK v1 still runs, and a script that works today is not broken by the existence of v2. The migration is only worth doing if something in your setup requires v2, or if v2 gives you something you want, and those are the only two reasons to spend the effort.
Licence, releases and what to check before you convert
The licence field on the repository says Unlicense, which is a public domain dedication in the style of the Unlicense text rather than a conventional open source licence. In practical terms it means the code is placed in the public domain and carries the usual disclaimer that it comes with no warranty. For a script that you will then edit by hand, that is a workable arrangement, and it is a common choice for small utility projects.
The project is not archived and the last push was on 2026-09-12, so it is being worked on. The release history shows v2.0 from 2026-04-18, v1.8 from 2025-10-23 and v1.7.1 from 2025-06-24, so the versioning has moved past 1.x into a 2.0 line for the tool itself, which is separate from the v1 to v2 subject matter the tool deals with and easy to confuse.
The repository layout shows a small number of top level scripts. Converter_UI.ahk is the GUI, v2converter.ahk is the file converter, QuickConvertorV2.ahk and QuickConvertorV2_scintilla.ahk are the fragment converters, with the Scintilla variant being the one with the richer editing pane. There is also ConvertFuncs.ahk, Global_Declare.ahk and GuiProg.ahk, plus convert/, diff/, lib/, tests/ and images/ directories, and an AutoHotKey Exe/ directory that bundles the v2 executable.
Four things to check before converting a script that matters to you.
That you have a copy of the original and a way to compare, since the visual diff and the compare buttons are the only way to see what the tool did to a given line.
That you read the known limitations page, because the variable name conflicts listed there are the most common source of a broken output.
That you read the line comments in the output, since the V1toV2 prefixed comments are where the tool tells you it was unsure.
And that you can run both versions, because the play buttons that run the v1 and the v2 code side by side are the fastest way to check a conversion, and the unit test mode exists so that changes to the converter can be checked against a stored set of expected results.
Editorial conclusion
AHK-v2-script-converter suits a script author with a large v1 codebase who wants the mechanical bulk of the migration done consistently and wants to be told, in the output, which parts still need a human. It is the wrong tool for a script that must convert perfectly unattended, since the README is explicit that manual edits should be expected and that the tool may not produce fully functional v2 code. Before converting a script you care about, read the known limitations, and if you use the Dynamic Gui mode, note that it needs an include file before or after conversion and produces a v2 syntax that differs from the other modes.
Frequently asked questions
What does the AHK-v2-script-converter do?
It rewrites AutoHotkey v1 script source into AHK v2 syntax. The README describes it as an assistant rather than a true converter, designed to automate the tedious parts of the migration, covering about 80 percent or more of the conversion automatically, with manual edits expected on the output.
How do I run the AutoHotkey v1 to v2 converter?
Download the full repository as a zip and run the included Converter_UI.ahk script with AutoHotkey v2, then choose one of the three conversion buttons. For a whole file you can run v2converter.ahk directly, and for a pasted fragment QuickConvertorV2.ahk, which also supports selecting text in another program and pressing XButton1 to convert it.
What are the Gui conversion modes in the AHK v2 converter?
ORIG, the original method that is being replaced, SIMPLE, an improved version recommended for simple non-dynamic v1 Gui syntax, DYNAMIC, recommended for the best results but with limited support for dynamic attributes and requiring an include file, and AUTO, which analyses the source and picks between Simple and Dynamic.
How does the AHK v2 converter compare with using an AI model?
The README argues that the tool gives fast, consistent output that has been pre-tested, and adds inspection comments for what it does not support instead of inventing invalid code, while an AI may hit token limits, drift semantically on long scripts, hallucinate or remove code, and compound errors through revision exchanges.
What are the known limitations of the AHK v2 converter?
The README asks you to read the known limitations page, starting with variable name conflicts, which it describes as very common and requiring manual attention. The Dynamic Gui mode also has limited support for dynamic attributes such as those within loops, function parameters, multiple scopes and ClassNN names, and the tool may not produce fully functional v2 code.
What licence is the AHK-v2-script-converter released under?
The Unlicense, a public domain dedication, with the terms in the LICENSE file at the root of the repository.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/mmikeww-ahk-v2-script-converter)Was this useful?