Clone wiki

thg / developers / MacOSX

Installing on Mac OS X

There are several ways to install TortoiseHg on Mac OS X.

DMG packages are also available, look for the most recent * at our downloads page

Install from Source

Dependencies: PyQt and QScintilla

0. Install Apple Development Tools (Xcode)

1. Install Qt4 (Qt SDK for Mac)

Direct access via

For Snow Leopard (10.6) users: python2.6 is now run on 64-bit environment by default. Please install 64-bit Qt binary, "Cocoa: Mac binary package for Mac OS X 10.5 - 10.6 (32-bit and 64-bit)".

Do not install Qt version 4.7.1 or 4.7.2. These versions generate crashes in some cases.

Note: Qt 4.7.0 does not crash but you will not be able to use keyboard shortcuts corresponding to contextual menu items. This version could be found on with all other versions.

2. Install QScintilla (from source)

$ cd Qt4
$ qmake -spec macx-g++
$ make
$ sudo make install

installed files:

  • /usr/include/Qsci
  • /Developer/Applications/Qt/translations/qscintilla_*
  • /usr/local/Qt4.6/qsci
  • /Library/Frameworks/libqscintilla*

(Optionally) install Qt Designer plugin:

$ cd designer-Qt4
$ qmake -spec macx-g++
$ make
$ sudo make install

installed files:

  • /Developer/Applications/Qt/plugins/designer/libqscintillaplugin.dylib

3. Install Sip (from source)

$ python
$ make
$ sudo make install

For Snow Leopard (10.6) users: If you installed 32-bit Qt, append -n --arch i386 to See,-Qt-on-osx-SnowLeopard-td26394590.html

installed files:

  • /System/Library/Frameworks/Python.framework/Versions/2.6/bin/sip
  • /Library/Python/2.6/site-packages/
  • /System/Library/Frameworks/Python.framework/Versions/2.6/include/python2.6/sip.h
  • /Library/Python/2.6/site-packages/
  • /Library/Python/2.6/site-packages/

4. Install PyQt (from source)

$ python
$ make
$ sudo make install

installed files:

  • /Library/Python/2.6/site-packages/PyQt4
  • /System/Library/Frameworks/Python.framework/Versions/2.6/share/sip/PyQt4
  • /System/Library/Frameworks/Python.framework/Versions/2.6/bin/pyuic4
  • /System/Library/Frameworks/Python.framework/Versions/2.6/bin/pylupdate4
  • /System/Library/Frameworks/Python.framework/Versions/2.6/bin/pyrcc4
  • /usr/local/Qt4.6/qsci/api/python/PyQt4.api

You may need to add /System/Library/Frameworks/Python.framework/Versions/2.6/bin to PATH; or create symlink to them:

$ for name in pyuic4 pylupdate4 pyrcc4; do sudo ln -s ../../../System/Library/Frameworks/Python.framework/Versions/2.6/bin/$name; done

Also, PyQt4 will install versions of pyuic4 for both Python 2 and Python 3, and py2app will find the wrong version when both are present. To work around this problem, simply delete the /Library/Python/2.6/site-packages/PyQt4/uic/port_v3 directory. If you see an error in when attempting to build, you most likely did not delete the port_v3 directory.

5. Install Python binding for QScintilla

$ cd Python
$ python
$ make
$ sudo make install

installed files:

  • /System/Library/Frameworks/Python.framework/Versions/2.6/share/sip/PyQt4/Qsci
  • /usr/local/Qt4.6/qsci/api/python/QScintilla2.api

6. Test installation

# Only for Snow Leopard (10.6) users who installed 32bit Qt:

$ python
Python 2.6.1 (r261:67515, Feb 11 2010, 00:51:29) 
[GCC 4.2.1 (Apple Inc. build 5646)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from PyQt4.QtGui import *
>>> app = QApplication([])
>>> w = QDialog()
>>> app.exec_()

Optional Dependencies

  • Install iniparse - allows thg to modify your configuration files
  • install pygments - enables auto-completion of source in commit tool

Get Latest Mercurial and TortoiseHg

$ hg clone mercurial
$ hg clone
$ cd mercurial
$ make local

Add ~/Documents/mercurial to PYTHONPATH, or symlink to them:

$ ln -s ../mercurial/mercurial
$ ln -s ../mercurial/hgext

Run it:

# Only for Snow Leopard (10.6) users who installed 32bit Qt:

$ thg log

Happy Hacking!

Install via Fink

TortoiseHg is now available in fink's unstable tree, as tortoisehg-py27 (or 25 or 26 if you are using an older python for some reason). You can get it prebuilt for 10.8 from Brendan Cully's unofficial apt repository for fink by adding deb stable main to /sw/etc/apt/sources.conf. After adding the repository, apt-get update and apt-get install tortoisehg-py27.

Install via Homebrew

Note: Qt now comes pre-compiled with homebrew. So installing TortoiseHg is much faster than it used to be.

Note: These steps have been confirmed to work with TortoiseHg 2.2.2. They also create an app for your Applications folder.

# Edit ~/.bash_profile or ~/.bashrc
# Add these lines (or adjust them)
BREW_PREFIX=`brew --prefix`
export PATH=$BREW_PREFIX/share/python:$BREW_PREFIX/bin/:$BREW_PREFIX/sbin:$PATH
export PYTHONPATH=$BREW_PREFIX/lib/python2.7/site-packages:$PYTHONPATH
  • Install PyQt via homebrew (this also installs qt and sip):
$ brew install pyqt
  • Install QScintilla via homebrew.
$ brew install qscintilla2
  • Install required Python packages:
$ easy_install pip
$ pip install -U Pygments iniparse Mercurial
  • Checkout TortoiseHg (using Mercurial):
$ hg clone ~/Documents/TortoiseHg
$ cd ~/Documents/TortoiseHg
$ hg update stable  # or hg update <version-number>

Now you should be able to start TortoiseHg:

$ ./thg log

The final step is to "create" a "wrapper app bundle" for your Mac OS X applications folder. Simply checkout this repository and copy the app bundle it contains to your Applications folder.

Note: If you've checked out TortoiseHg to /Documents/TortoiseHg, this app should work out of the box. Otherwise you need to read the readme file included in the repository.

Troubleshooting the Homebrew alternative

  • If there is an error about missing git repository, try to update Homebrew first: $ brew update
  • If you get ImportError: No module named PyQt4.uic.Compiler, make sure Homebrew's Python path is in $PYTHONPATH.

Install via MacPorts

Warning: Installing TortoiseHg this way usually takes a couple of hours because Qt is compiled from its sources.

  • Install XCode (Version 3.x is free and works)
  • Install Python and PyQt from ports:
$ sudo port install python27 python_select
# Make this the default version
# Old version: $ sudo python_select python27
# New version:
$ sudo port select python python27

$ sudo port install py27-pyqt4 py27-qscintilla
  • Set " /opt/local/Library/Frameworks/Python.framework/Versions/2.7/bin" to your Path (edit /.bash_profile)
  • Install pip (if not present)
$ curl -O
$ sudo python
$ sudo easy_install pip
  • Install the easy_installable thg fork
$ sudo pip install thg-mac