docs/starting/install/osx.rst

   1 .. _install-osx:
   2
   3 Installing Python on Mac OS X
   4 =============================
   5
   6 The latest version of Mac OS X, Lion, **comes with Python 2.7 out of the box**.
   7
   8 You do not need to install or configure anything else to use Python. Having
   9 said that, I would strongly recommend that you install the tools and libraries
  10 described in the next section before you start building Python applications
  11 for real-world use. In particular, you should always install Distribute, as it
  12 makes it much easier for you to use other third-party Python libraries.
  13
  14 The version of Python that ships with OS X is great for learning, but it's not
  15 good for development. It's slightly out of date, and Apple has made significant
  16 changes that can cause hidden bugs.
  17
  18 Doing it Right
  19 --------------
  20
  21 Let's install a real version of Python.
  22
  23 First, you'll need to have GCC installed to compile Python. You can either get
  24 this from `XCode <http://developer.apple.com/xcode/>`_ or the smaller
  25 `OSX-GCC-Installer <https://github.com/kennethreitz/osx-gcc-installer#readme>`_ package.
  26
  27 While Lion comes with a large number of UNIX utilities, those familiar with
  28 Linux systems will notice one key component missing: a decent package manager.
  29 `Homebrew <http://mxcl.github.com/homebrew/>`_ fills this void.
  30
  31 To `install Homebrew <https://github.com/mxcl/homebrew/wiki/installation>`_,
  32 simply run
  33
  34 .. code-block:: console
  35
  36     $ /usr/bin/ruby -e "$(/usr/bin/curl -fsSL https://raw.github.com/mxcl/homebrew/master/Library/Contributions/install_homebrew.rb)"
  37
  38 Then, insert the Homebrew directory at the top of your ``PATH`` enviornment
  39 variable. You can do this by adding the following line at the bottom of your
  40 ``~/.bashrc`` file
  41
  42 .. code-block:: console
  43
  44     export PATH=/usr/local/bin:$PATH
  45
  46 Now, we can install Python 2.7: ::
  47
  48     $ brew install python --framework
  49
  50 This will take a minute or two. Once that's complete, you'll have to add the
  51 new Python scripts directory to your ``PATH``
  52
  53 .. code-block:: console
  54
  55     export PATH=/usr/local/share/python:$PATH
  56
  57 The ``--framework`` option tells Homebrew to compile a Framework-style Python
  58 build, rather than a UNIX-style build. The outdated version of Python that
  59 Snow Leopard comes packaged with is built as a Framework, so this helps avoid
  60 some future module installation bugs.
  61
  62
  63 Distribute & Pip
  64 ----------------
  65
  66 The most crucial third-party Python software of all is Distribute, which
  67 extends the packaging and installation facilities provided by the distutils
  68 in the standard library. Once you add Distribute to your Python system you can
  69 download and install any compliant Python software product with a single
  70 command. It also enables you to add this network installation capability to
  71 your own Python software with very little work.
  72
  73 Homebrew already installed Distribute for you. Its ``easy_install`` command is
  74 considered by many to be deprecated, so we will install its replacement:
  75 **pip**. Pip allows for uninstallation of packages, and is actively maintained,
  76 unlike easy_install.
  77
  78 To install pip, simply open a command prompt and run
  79
  80 .. code-block:: console
  81
  82     $ easy_install pip
  83
  84
  85 Virtualenv
  86 ----------
  87
  88 After Distribute & Pip, the next development tool that you should install is
  89 `virtualenv <http://pypi.python.org/pypi/virtualenv/>`_. Use pip
  90
  91 .. code-block:: console
  92
  93     $ pip install virtualenv
  94
  95 The virtualenv kit provides the ability to create virtual Python environments
  96 that do not interfere with either each other, or the main Python installation.
  97 If you install virtualenv before you begin coding then you can get into the
  98 habit of using it to create completely clean Python environments for each
  99 project. This is particularly important for Web development, where each
 100 framework and application will have many dependencies.
 101
 102 To set up a new Python environment, change the working directory to where ever
 103 you want to store the environment, and run the virtualenv utility in your
 104 project's directory
 105
 106 .. code-block:: console
 107
 108     $ virtualenv --distribute venv
 109
 110 To use an environment, run ``source venv/bin/activate``. Your command prompt
 111 will change to show the active environment. Once you have finished working in
 112 the current virtual environment, run ``deactivate`` to restore your settings
 113 to normal.
 114
 115 Each new environment automatically includes a copy of ``pip``, so that you can
 116 setup the third-party libraries and tools that you want to use in that
 117 environment. Put your own code within a subdirectory of the environment,
 118 however you wish. When you no longer need a particular environment, simply
 119 copy your code out of it, and then delete the main directory for the environment.
 120
 121
 122 --------------------------------
 123
 124 This page is a remixed version of `another guide <http://www.stuartellis.eu/articles/python-development-windows/>`_,
 125 which is available under the same license.