Skip to end of metadata
Go to start of metadata

To use Bitbucket, you need to install a DVCS tool on the computer where you write your code. Typically, this computer is a machine physically close to you like your home or work computer. This is your local machine or system. You also might write or deploy code to a remote machine – for example a lab computer or a server in a data center. You may also need a DVCS tool on that machine too. This tutorial refers to the typical case, your local system, but the instructions are the same for both cases.

Bitbucket supports two DVCS tools, Git and Mercurial. These tools run on all modern operating systems.  For Git, Bitbucket supports 1.6.6 or later and Mercurial version 1.7 or later. Mercurial also requires (depends on) the Python programming language. The installation process takes care of making sure you get the correct version of Python.

Since you can use both Git and Mercurial on the same machine, this page shows you how to install both because you need both to complete this tutorial.  If you already have these tools installed, skip the instructions and go to the next step in the tutorial.

Windows or Linux User?

Microsoft Windows users see this page.
Linux users see this page.

Step 1. Install Git

If you are using a Mac, you may already have Git. To find out, open a terminal and enter git --version.

$ git --version
git version 2.3.2

If you receive a version number, as shown in the previous example, great! You have Git already and can continue to the next step. If not, install Git.

If you run into issues while following these instructions, make sure you have root access (sudo) on the system where you want to install Git.

  1. Download the Git installer from its official website.  
    The installer is a DMG file. 
  2. Double-click the DMG to expand it.
  3. Double-click the PKG file to install it.
    The Git installer launches.
  4. Follow the prompts to install Git.
  5. Open a terminal on your system.
  6. Verify the installation was successful by typing which git --version at the command line.

    $ git --version
    git version 2.3.2

    Depending on the version you install, the command line may return a different version.

Step 2. (Optional) Install the git-credential-osxkeychain helper

Bitbucket supports pushing and pulling over HTTP to your remote Git repositories on Bitbucket. Every time you interact with the remote repository, you must supply a username/password combination.  Instead of supplying the combination with every HTTP call, you can store these credentials in your OSX keychain provided you have the git-credential-osxkeychain helper added to Git.  

The helper asks for your username/password on the first Git operation and then stores the credential. Future operations won't require you to supply a username/password combination. To install the helper, open a terminal window on your local system and do the following:

  1.  Check if you have the helper installed by determining if you get a usage statement for it.

    $ git credential-osxkeychain
    usage: git credential-osxkeychain <get|store|erase>

    If you receive a usage statement, skip to Step 5.  If the helper is not installed, go to the next step.

  2. Download the git-credential-osxkeychain software to your source with curl;

    $ curl -O 

    This command downloads the source to a local file called git-credential-osxkeychain.  If you don't have curl installed you can use this link

  3. Move the file to the /usr/local/bin directory.

    $ sudo mv git-credential-osxkeychain /usr/local/bin/
  4. Make the file an executable:

    $ chmod u+x /usr/local/bin/git-credential-osxkeychain 
  5. Configure git to use the helper.

    $ git config --global credential.helper osxkeychain
    # Set git to use the osxkeychain credential helper

Step 3. Install Mercurial

You can use Mercurial from the command line or you can use one of several GUI-based tools such as Sourcetree.  These instructions assume you are using Mercurial from the command-line.

  1. Make sure you have root access (sudo) on the system where you want to install Mercurial.
  2. Download the Mercurial installer from its official website.  
    The installer is contained in  ZIP file.
  3. Double-click the ZIP file to expand it.
  4. Double-click the MPKG file to run the installer.
  5. Follow the prompts to complete the installation.
  6. Open a terminal window.
  7. Verify the installation was successful by typing the following at the command line.

    $ hg --version

    Hg is the chemical symbol for Mercury and hg is the command for mercurial. 

  8. Determine if you already have a ~/.hgrc file in your environment by entering the following at the command line:

    ls ~/.hgrc

    If for some reason, you don't have the .hgrc file, you should create one yourself using the touch command:

    touch ~/.hgrc

    Files that start with a . (period) are hidden files in Mac OSX. By default, the Finder does not show these files. To reveal hidden files, enter the following command into the terminal:

    defaults write AppleShowAllFiles YES

    To hide them files once again, enter the following command:

    defaults write AppleShowAllFiles NO
  9. Open the Mercurial configuration file ~/.hgrc  using your favorite editor.
  10. Add a username value to the configuration.

    When you are done, the ~/.hgrc file includes the following lines with your own username and email address:

    # Name data to appear in commits
    username = Mary Anthony <>

    This is default value Mercurial uses, you can also set this for specific repositories (you'll learn more about this later).

  11. Save and close the .hgrc file.


The next step is to Create an Account and a Git Repo 


  1. Ok. I then understand that my git is fine.

    And I think that I have fixed partially credentials error, but once re-installed new git-credential-osxkeychain, as in StackOverflow answer says, when I try to clone repository get another error:

    fatal: Authentication failed

    Than seems there are some yet wrong. I searched for a solution and I find this thread: fatal: Authentication failed but recommend me install Homebrew that require install Xcode and for Snow Leopard 10.6.8, which is a size of 4.14Gb! There aren't an alternative solution more simple? And Is mandatory have installed a port (Homebrew or Macports) to continue?

    Thank you!

    1. You do not need any package manager.  You can simply install git using the installer provided by git: <>.  That said, it appears you already have a working copy of git.  The problem is that git has been configured (probably by the installer) with a "credential helper" that is trying and failing to use your keychain for the bitbucket password.  In Terminal, enter

      git config --get-all credential.helper


      You should get the answer "osxkeychain".  The simplest solution is to turn this setting off.  This is probably set in your system gitconfig (/usr/local/git/etc/gitconfig).  If so, 

      sudo git config --system --unset credential.helper


      will turn it off (after you enter your login password).  If the setting is in your local gitconfig (~/.gitconfig), enter the following in Terminal:

      git config --local --unset credential.helper


      Either way, you can verify it is off by entering the "git config --get-all credential.helper" command again and getting no output.  Once it's off, the error message will disappear, and you will be prompted for your Bitbucket password whenever you have git interact with Bitbucket, as described in the tutorial.


    2. Miguel,

      Hopefully you are sorted out.  I'll be removing this thread in the next day or two.



  2. Hi Mary and Michael I have fixed error finally. It was related with credential.helper as Michael said. Thank you very much both! (wink)

    1. That is great. I'm glad you got it sorted!

  3. Anonymous

    Why get both Git and Mercurial? It sounds as though they do the same thing and I do have limited resources. If bitbucket is a "hosted DVCS service" (whatever that means)  - just who does what? Remember, I'm a newbie, I don't have any expectations of offering software to the public in the near future, so why would I want this now?  You talk about newcomers to coding, but I'm even newer to developing - I'm just peeping through the door. I  came here because the Python tutorial said to. Starting off with an explanation of DVCS and the relationships/rolls of the different players would be helpful.
    1. Hi,

      Thank you for the comment.  I understand your frustration.  Unfortunately, it is very hard to write one document that everyone at all levels find useful.  There is a curve and I try to hit it in the middle with bits on either end to help out those folks.  We have some videos to help out people who are investigating: That should give you an overview. Version control is a developer concept so if you are totally new to developing, you should google around to learn more.  This guide assumes that a user has a basic understanding of programming concepts.  I'll update the intro to clarify this.


  4. For those who experiment problem with git "comment not found" here is a little workaround : 

    1. open your ~/.bash_profile:
    $ sudo vi ~/.bash_profile

    2. add this line to the file:
    export PATH=$PATH:/usr/local/git/bin/

    3. Save & close the file:
    $ ESC, :wq, ENTER

    4. Restart your terminal and try :

    $ git --version


    Hope it helped someone (smile)

  5. Excuse me, but where is step 2? or Mercurial should be the second step?



    1. Mercurial should be the second step and now it is!  Thank you for the catch.

  6. Anonymous

    can't find .hgrc file

    1. Anonymous

      to open .hgrc open terminal and write

      open -a TextEdit .hgrc

  7. Anonymous

    Hi everyone, I got this while trying to install Mercurial, any advise??

    $ hg --version
    'import site' failed; use -v for traceback
    Traceback (most recent call last):
    File "/usr/local/bin/hg", line 10, in <module>
    import os
    File "/Library/Frameworks/Python.framework/Versions/7.3/lib/python2.7/", line 398, in <module>
    import UserDict
    File "/Library/Frameworks/Python.framework/Versions/7.3/lib/python2.7/", line 84, in <module>
    File "/Library/Frameworks/Python.framework/Versions/7.3/lib/python2.7/", line 109, in register
    if issubclass(subclass, cls):
    File "/Library/Frameworks/Python.framework/Versions/7.3/lib/python2.7/", line 184, in __subclasscheck__
    File "/Library/Frameworks/Python.framework/Versions/7.3/lib/python2.7/", line 84, in add, self._remove))
    TypeError: cannot create weak reference to 'classobj' object

    1. Sounds like  your install failed.  Remove the bad installation and try reinstalling Mercurial.

      1. Anonymous

        Hi Mary, I tried that already and didn't work. I found a solution in stackoverflow, apparently I'm not the only one... It consists on emptying the PYTHONPATH, it works, but it's not a good solution, at least for me...

        Any help would be appreciated,


        Here's the link:

  8. Anonymous

    I believe the step 2 is wrong. You should swap the order of substeps 3 and 4!

  9. Anonymous

    But then you should also use sudo on the chmod command. Better is to change Step 2.3:

    $ chmod u+x git-credential-osxkeychain 
  10. Anonymous

    You should use this path for part 3 of step 2: 

    chmod u+x /usr/local/git/bin/git-credential-osxkeychain