Windows file associations

From Vim Tips Wiki

Jump to: navigation, search
Tip 1003 Printable Monobook Previous Next

created 2005 · complexity basic · version 6.0


Although the Vim installer gives you options to create right-click "edit with Vim" options, it is convenient to be able to simply double-click on a file to have it open in Vim. This "double-click to open" is commonly referred to as a "file association" and is fairly easy to set up in Microsoft Windows. You can use the "Open With..." menu in Windows to set up a basic association, but that will not allow you to specify any command-line arguments to Vim, such as --remote-silent to open with an existing Vim instance. In order to fully specify the action to take when double-clicking a file, Windows provides the ftype and assoc command-line tools.

To use, simply open a Windows command prompt and type something like the following:

assoc .php=PHPFile
ftype PHPFile="C:\Program Files\Vim\vim72\gvim.exe" --remote-silent "%1"

This particular command sequence will set up Windows to open any files with a .php extension in an existing gvim window (or it will open new gvim window if there is no already opened gvim window).

In general, the assoc command is used to associate a given file extension with a filetype. The ftype command is used to tell Windows what to do to open files of a given file type. You can associate any number of file extensions with a given filetype, which makes it easy to set up a single action for similar types of files. For example, the following will treat any files with extensions .c, .h, .pl, or .py as "sourcecode", which it will launch in Vim as we did with PHPFile above:

assoc .c=sourcecode
assoc .h=sourcecode
assoc .pl=sourcecode
assoc .py=sourcecode
ftype sourcecode="C:\Program Files\Vim\vim72\gvim.exe" --remote-silent "%1"

[edit] How it works

Both the ftype and assoc commands work by creating entries in a specific registry location which Windows will check for various actions taken on a file. The easiest and safest way to create these entries is to use the command-line tools, but it is possible to create them by hand.

assoc .c=sourcecode will create a registry key at HKEY_CLASSES_ROOT\.c that has a (Default) value of sourcecode. When you double-click on a .c file, Windows will see this key and look for another key to figure out what to do with a sourcecode file.

ftype sourcecode="C:\Program Files\Vim\vim72\gvim.exe" "%1" will set up another registry entry, in HKEY_CLASSES_ROOT\sourcecode\Shell\Open\command with (Default) value of "C:\Program Files\Vim\vim72\gvim.exe" "%1". This entry could do with more inspection.

[edit] Associating Vim with other actions

Consider the .html file extension. For most users, it would not make sense to open a .html file in Vim when double-clicking the file. Most users would want the file to open in a web browser when double-clicking, but being able to automatically edit the file in Vim when modifying the file would be a nice thing to be able to do. This is where the registry entry created by ftype comes in.

WARNING: Editing your Windows registry may cause unintended side effects that render your system inoperable. Although this tip has worked in the past for some people, there is no guarantee that it will work for you. Use with caution, and at your own risk.

There are no easy command-line or GUI tools to do this, but you can set up other actions, such as "edit", in the same registry area that ftype uses. Simply replace the "open" portion of the registry key path with the desired action (in this case, "edit"). For example, assume that .html files have been associated with a filetype called htmlfile. Then, to keep the existing double-click action in place, but add Vim as the "edit" action, give the following registry key a (Default) value of "C:\Program Files\Vim\vim72\gvim.exe" "%1": HKEY_CLASSES_ROOT\htmlfile\Shell\Edit\command

Edit action file association reg key

Registry entry for the "edit" action

Note: in Windows XP, there is a GUI for doing this, accessible through the "Folder Options" dialog.

Now, you can double-click on a .html file to open it in your web browser as normal. But you can also right-click on the file, and choose "Edit" from the context menu. This will open the file in gvim.

Do not limit yourself to just edit actions! For example, you could make an entry to open gvim on a directory, load configuration files, or source scripts.

[edit] User-specific file associations

Unfortunately, all of the methods mentioned above apply your file associations in an area of the registry used by every user account in your Windows installation. This means that if you are on a multi-user system, and you are the only user using Vim, other people will get very annoyed if you use these tools to make files launch in Vim.

Luckily, although Windows does not provide a GUI or even easy command-line tools to edit or change it, Windows 2000 and above provide a place in the registry that can be used to store user-specific file associations. This place is HKEY_CURRENT_USER\Software\Classes. Creating a file association here uses two steps, which duplicate what the assoc and ftype commands do in their registry area. For an example, we will associate the ".c" extension to the "sourcecode" filetype, and then tell Windows to launch anything in the "sourcecode" filetype in gvim version 7.2, opening the file in a new tab. It should be easy to adjust this as desired.

WARNING: Editing your Windows registry may cause unintended side effects that render your system inoperable. Although this tip has worked in the past for some people, there is no guarantee that it will work for you. Use with caution, and at your own risk.

[edit] Step 1: associate the file extension with a file type

To do this, you need only create a registry key with the name of the file extension desired and a default value of the filetype you want to associate with it. For our example, you would create the key, HKEY_CURRENT_USER\Software\Classes\.c (using regedit or the command-line "reg add" command). In regedit, you can see a (Default) value for this key after creating it. Set the value to sourcecode.

User-specific associations assoc reg key

Registry entry for file extension association

[edit] Step 2: associate the filetype with gvim

The next step is to tell Windows what to do with your new filetype, just like the ftype command.

First, create the key HKEY_CURRENT_USER\Software\Classes\sourcecode\shell\open\command. This key will also have a (Default) value, which you need to set to the program used to open files of this type. For example, you could set it to "C:\Program Files\Vim\vim72\gvim.exe" --remote-tab-silent "%1" to open .c files (and other sourcecode typed files) in a new tab in the default gvim.

User-specific associations ftype reg key

Registry entry for filetype action

Just as we explained above, you can specify other actions to take besides opening on a double-click, simply by replacing "open" with the appropriate action in the registry key path.

[edit] Scripting the additions

Windows does provide a command-line utility for editing the registry: reg add. You can use this tool from a CMD prompt, but it is probably more useful to create a batch file containing commands to set all your desired file associations.

You need to escape double-quote characters with a backslash. To set the (Default) value we need, provide an empty string as the value name using /v "". In a batch file, you also need to escape the '%' character with a second '%' character. With this in mind, the following lines in a batch file will set up the file association given in our example above:

reg add HKCU\SOFTWARE\Classes\.c /v "" /t REG_SZ /d "sourcecode" /f
reg add HKCU\SOFTWARE\Classes\sourcecode\shell\open\command /v "" /t REG_SZ /d "\"C:\Program Files\Vim\vim72\gvim.exe\" --remote-tab-silent \"%%1\"" /f

[edit] See also

[edit] Comments

 TO DO 

  • For user-specific associations, should also mention creating and merging a reg file, which is probably easier.
  • The usual Windows escape character is "^". Why do we need to escape quotes with a backslash in the "reg add" command? This seems weird, but it works.

The following is a "for reader's information" comment; not a suggestion that the tip be changed. In classic Microsoft style, using HKEY_CLASSES_ROOT is ambiguous. I do not know the details, but on at least some systems (after Windows 9x), I think the following is correct:

HKEY_LOCAL_MACHINE\Software\Classes : for all users
HKEY_CURRENT_USER\Software\Classes : for interactive user
HKEY_CLASSES_ROOT : merged view of above (and is used by Win9x apps)

I don't know what happens if you write to HKEY_CLASSES_ROOT (which does not exist). Perhaps (like installing some apps), if you are in the Administrators group, you will write to HKLM, otherwise you will write to HKCU. JohnBeckett 08:24, 2 July 2009 (UTC)


This is correct as far as I know. I wanted to include some information about how HKCR is a merged view of HKLM/Software/Classes and HKCU/Software/Classes, but doing so would beg information such as "what happens when I edit an entry that actually exists in HKCU?" etc. From experimentation, it seems that creating new keys in this area will always create it in HKLM (system-wide), and ftype and assoc certainly do that, but I don't really have any documentation of that fact, and I don't know what it will do for limited-privilege accounts. I also don't know what happens when you edit an existing key, but I imagine it will "do the right thing" and keep the original where it was. I don't know this for a fact though. For these reasons, I left out that tidbit. But if we can answer some of these questions, it would be a good thing to include.

--Fritzophrenic 15:19, 2 July 2009 (UTC)


The HKEY_CLASSES_ROOT key provides a merged view of HKEY_LOCAL_MACHINE\Software\Classes and HKEY_CURRENT_USER\Software\Classes.

When reading, the HKEY_CURRENT_USER settings have priority over the HKEY_LOCAL_MACHINE settings.

If you write values to a key under HKEY_CLASSES_ROOT, the values will:

  1. Go under HKEY_CURRENT_USER\Software\Classes if a HKEY_CURRENT_USER\Software\Classes\key previously existed under HKEY_CURRENT_USER\Software\Classes.
  2. Go under HKEY_LOCAL_MACHINE\Software\Classes otherwise.

--December 23, 2012


Perhaps Tip 1301 could be merged in here, by adding

assoc .=sourcecode

to the examples, with a comment syaing it applies to a file with no extension?

JLittle 21:27, November 10, 2009 (UTC)

Yes, and probably also Open_Vim_Here_by_clicking_the_context_menu_on_a_folder/directory_on_Windows. Maybe we can create a "special cases" section that includes both of these, and potentially other "reserved" values that can be used? --Fritzophrenic 21:44, November 10, 2009 (UTC)
Personal tools