Note: you probably want the prepackaged Windows version from BinaryPackages!

In this web page firstly you will find a 'standard' procedure to install and config Mercurial from sources under Windows. It should satisfy you generally. If not, you could continue reading for various tips and references provided by various contributors in history. Some of them are valuable although some of them are a bit out of date.


'Standard' procedure

1. Download Python binary such as python-2.6.1.msi from []. Install it to C:\Python26 as defaut.

Caution: Don't use Active Python in [] or you will probably fail to build Mercurial from source.

2. Download MinGW binary such as MinGW-5.1.4.exe from []. Download it to a writable directory. Install it to C:\MinGW as default, with other default opinions ("Current", and then "min").

3. Add C:\MinGW\bin to PATH env. It should looks like

C:\python26;bla bla bla;C:\MinGW\bin

Caution: The order is important. Keep it or you will probably fail to build.

4. Download Mercurial source such as mercurial-1.1.2.tar.gz from []. Unpack it to C:\Mercurial_src.

Caution: Check to make sure you didn't unpack it to C:\Mercurial_src\mercurial-1.1.2 or similar.

5. In Windows command prompt, change dir to C:\Mercurial_src. Then run following commands:

python build --force -c mingw32
python install --force --skip-build

6. Download KDiff3 such as KDiff3Setup_0.9.95.exe from []. Install it into C:\Program Files\KDiff3 as default.

7. Add C:\Program Files\KDiff3 to PATH env.

8. Create Mercurial config file

Notepad "C:\Documents and Settings\your_name\.hgrc"

Fill in content below into the config file:

editor = Notepad
username = your_name <your_email_address>

kdiff3.args=-L1 base --L2 local --L3 other $base $local $other -o $output

9. (Nice to have) Copy from C:\Python26\Scripts\hg to C:\Python26\ As C:\Python26 is in your PATH env already, you could call to run Mercurial at any location. As you may installed or will install binary Mercurial or TortoiseHG, you could always call to run this script version of Mercurial, or call hg which will lead you to the binary version.

Various Tips and References

1. Overview

To install Mercurial from sources under Windows, you need

If you are using []'s Python, you will find that the [ win32 API extensions] make a huge performance difference when you use the clone command (but see the caveats below about hardlinks on Windows). If you are using Python 2.4, you will also need [ mfc71.dll]. (These extensions are already shipped as part of [ ActivePython], but ActivePython is not completely open source software.)

See [:BuildingWindowsInstaller] for instructions to build a Mercurial installer. [:BuildingOnWindows] has some hints about how to build Mercurial on Windows.

This pages describes some issues you may meet when trying to install Mercurial, and how to solve them.

Ideally, you would only need to run

python install --force

in the directory where you unpacked the sources, and everything would "just work". The use of -f/--force switch makes sure that any old installation is overwritten.

2. Build Tips

2.1. MingW32

2.1.1. Using MingW32

By default, Python and ActivePython will look for Microsoft Visual C to compile the extensions, so you have to tell to use the MingW32 compiler instead. You can do this by running

python build --force -c mingw32
python install --force --skip-build

or more briefly:

python build -f -c mingw32 install -f

If you are not familiar with mingw32, you will first need to download and install the following packages, in the order given:


Afterwards, download and install the following package, installing it in the directory where you installed the msys package (i.e. c:\msys\1.0\)


You can find them at

Then add the Python and mingw directories to your PATH, and run your build from the command prompt:

set PATH=%PATH%;c:\python24;c:\msys\1.0\mingw\bin

If you encounter compiler error in Mercurial versions 0.9.2 and up, you may need libpython24.a in PYTHONPATH\libs. If that's the case, you need to:

pexports C:\WINDOWS\system32\python24.dll > python24.def
dlltool --dllname C:\WINDOWS\system32\python24.dll --def python24.def --output-lib C:\Python24\libs\libpython24.a

Then the above script should run properly.

2.1.2. Easier MingW32 based build via Cygwin

It is easier to install MinGW32 via Cygwin as it has a single graphical installer. After installing, mingw32 via Cygwin installer (setup.exe), add cygwin bin directory to the path and follow the mingw32 build instructions. e.g.

set PATH=%PATH%;c:\python24;c:\cygwin\bin
python build --force -c mingw32
python install --force --skip-build

2.2. MS Visual Studio

2.2.1. Using MSVC

If you are going to use MS Visual C++, you normally need to use the same version of the compiler as the one which was used to build the Python interpreter. For example:

But it's also possible to force Python to use the compiler that you currently have, even if it's not strictly matching.

For this, you can use a shell with the environment already set up for compilation, and then tell distutils that it has to trust the compiler available from the path:

set MSSdk=1

(see [ distutils msvc] doc)

If you don't do the above and simply run python build, you'll likely get errors, for example, the following one:

AttributeError: MSVCCompiler instance has no attribute '_MSVCCompiler__root'

Additional caveat: if you're using Python 2.6, also have a look at

This way, I've successfully built Mercurial using Visual Studio 2005 (VC++ 8) for's Python 2.5 (amd64) and 2.6 (win32/amd64). But Python 2.5 (win32) really insisted on using Visual Studio 2003...

In the past, I also successfully built Mercurial using the Platform SDK compiler (I used the Microsoft Platform SDK for Windows Server 2003 R2).

Another, less than ideal, work-around for the version check is to change your distutils notion of what version of MSVC Python was built with. Do this by editing your file in your python/Lib/distutils directory to match the version of MSVC you actually have, for example:

   def __init__ (self, verbose=0, dry_run=0, force=0):
       CCompiler.__init__ (self, verbose, dry_run, force)
       self.__version = get_build_version()
 +     self.__version = 6 # override build version to match compiler

(well, this didn't work for me, use the MSSdk/DISTUTILS_USE_SDK trick -- cboos)

2.2.2. MS VC++ 8 / Python 2.5 (amd64) Notes

If you actually have the above combination (and use the DISTUTILS_USE_SDK way described above), you'll probably manage to build the extensions, but they won't load:

ImportError: DLL load failed with error code 193

Or some similar error, like abort: could not import module found.!.

The fix is to embed the .manifest files into the .pyd modules using [ mt.exe]:

# (assuming you're in a cygwin bash shell)
$ python build_ext
$ cd build/lib.win32-2.5/mercurial
$ for pyd in *.pyd; do mt.exe -nologo -outputresource:$pyd\;2 -manifest $pyd.manifest; done
$ cd ../../..
$ python install

Note that build/lib.win32-2.5 in the above is not a typo, Python 2.5 (amd64) really uses that directory name.

OTOH, Python 2.6's distutils do this right when using VS 2005 (and most probably also when using VS 2008, though I didn't verify). Even the build directory is correct when building the 64-bits version: build/lib.amd64-2.6

3. Install Tips

3.1. Where is my Mercurial?

By default, Mercurial (the executable) gets installed in a Scripts folder under your Python installation folder.

You can create a small batch file in a folder which is present in your path (e.g. your Windows installation folder) to help you launch Mercurial.

If you are running a Windows of the 9x series (Windows 95, 98 or ME), create a file called hg.bat with the following content:

@echo off
python <path-to-Scripts-folder>\hg %0 %1 %2 %3 %4 %5 %6 %7 %8 %9

For example, if you installed Python in c:\python, the content of the file would be

@echo off
python c:\python\hg %0 %1 %2 %3 %4 %5 %6 %7 %8 %9

Under Windows NT, create a file called hg.cmd with the following content:

@python <path-to-Scripts-folder>\hg %*

For example, if you installed Python in c:\python, the content of the file would be

@python c:\python\Scripts\hg %*

An alternative scheme that works better for some is to search for hg on the PATH. If you are using hg.exe it should work fine. For the python version of hg you should be able to simply rename 'hg' to '' and assuming you have the .py extension configured it will be invoked. It is invoked, but there is a long standing redirection bug in Windows, and on XP there are sometimes problems with exit statuses being lost with this form of execution. So the following batch file is a solution -- place it in your PATH and it will find 'hg' without a .py extension in you PATH and invoke it properly: (name the file hg.cmd)

@echo off
for /f %%i in ("hg") DO set HGSCRIPT="%%~$PATH:i"
if %HGSCRIPT% == "" (
        echo Cannot find hg on PATH
        exit /b 1
python %HGSCRIPT% %*

An alternative is to add .py to the PATHEXT environment variable. Provided you have .py files set-up to run automatically when invoked, this allows you to run python scripts from the command line without the ending .py. This option also works if you are using UTF-8 in the Windows console (i.e code page 65001) which causes BAT and CMD files to stop working.

3.2. Other miscellaneous issues

WinZip7 does not seem to create empty files when extracting from .tar files. But WinZip9 is fine.

Earlier versions of mercurial had trouble handling tildes in glob patterns on windows. Upgrade if you encounter this problem.

3.2.1. Using the SSH protocol

Three solutions:

Edit the Mercurial.ini to have the following entry:

ssh = C:\cygwin\bin\ssh.exe

3.3. Fix the path problem on Windows

If you try to use hg inside a directory that has a 'mercurial' subdirectory, for example when working on the mercurial sources, python may not be able to load the binary modules needed by Mercurial, and you may get a stack trace like:

  File "C:\projects\hg\mercurial\", line 54, in module
    return object.__getattribute__(self, 'importer').module()
  File "C:\projects\hg\mercurial\", line 30, in module
  File "C:\projects\hg\mercurial\", line 9, in ?
    import struct, bdiff, util, mpatch
ImportError: No module named bdiff

See the mail list thread "Fix the path problem on Windows..." but essentially Python on Windows ends up with the current directory automatically added to the python search path before the site libraries. So if you run hg in its own repository python gets confused, and can't find the extensions needed. There is a candidate patch that removes the current directory, but there is an arguably better workaround from K.Thananchayan. Simply add a registry entry (replacing 2.4 with the version of Python)

   (Default) REG_SZ "YYY"

Mercurial now includes support for cloning with hardlinks on Windows. However for this to work, your filesystem needs to support them (i.e. NTFS) and you need the win32 API extensions documented above. If you have a filesystem that does not support hardlinks or don't have the win32file module from pywin32, mercurial clone will still work just fine - but you won't get the benefits of hardlinking of course. Note that pywin32 is only available for the Windows/x64 platform starting with Python 2.6. 32-bit Windows has been supported by pywin32 since Python 2.2.

For versions of Mercurial prior to 0.7, Mercurial won't realise that it has to 'break' hardlinks.

The upshot is that if you have repositories cloned with hardlinks you must not use pre-0.7 versions of mercurial on them (either the source or the destination clone), or use a version of python without win32file. If you do you are likely to get corruption.

A simple solution to break the hardlinks is to copy (using xcopy or File Explorer) one of the repositories, deleting the clone. Copying it back afterwards.

3.5. Default editor

The default editor for commit messages is 'vi'. The Windows installer creates a mercurial.ini that sets it to notepad. You can set the EDITOR (or HGEDITOR) environment variable to specify your preference or set it in mercurial.ini:

editor = whatever