1.. _installing_chapter: 2 3Installing :app:`Pyramid` 4========================= 5 6.. note:: 7 8 This installation guide emphasizes the use of Python 3.4 and greater for 9 simplicity. 10 11 12.. index:: 13 single: install preparation 14 15Before You Install Pyramid 16-------------------------- 17 18Install Python version 3.4 or greater for your operating system, and satisfy 19the :ref:`requirements-for-installing-packages`, as described in 20the following sections. 21 22.. sidebar:: Python Versions 23 24 As of this writing, :app:`Pyramid` has been tested under Python 2.7, 25 Python 3.3, Python 3.4, Python 3.5, PyPy, and PyPy3. :app:`Pyramid` does 26 not run under any version of Python before 2.7. 27 28:app:`Pyramid` is known to run on all popular UNIX-like systems such as Linux, 29Mac OS X, and FreeBSD, as well as on Windows platforms. It is also known to 30run on :term:`PyPy` (1.9+). 31 32:app:`Pyramid` installation does not require the compilation of any C code. 33However, some :app:`Pyramid` dependencies may attempt to build binary 34extensions from C code for performance speed ups. If a compiler or Python 35headers are unavailable, the dependency will fall back to using pure Python 36instead. 37 38.. note:: 39 40 If you see any warnings or errors related to failing to compile the binary 41 extensions, in most cases you may safely ignore those errors. If you wish to 42 use the binary extensions, please verify that you have a functioning 43 compiler and the Python header files installed for your operating system. 44 45 46.. _for-mac-os-x-users: 47 48For Mac OS X Users 49~~~~~~~~~~~~~~~~~~ 50 51Python comes pre-installed on Mac OS X, but due to Apple's release cycle, it is 52often out of date. Unless you have a need for a specific earlier version, it is 53recommended to install the latest 3.x version of Python. 54 55You can install the latest verion of Python for Mac OS X from the binaries on 56`python.org <https://www.python.org/downloads/mac-osx/>`_. 57 58Alternatively, you can use the `homebrew <http://brew.sh/>`_ package manager. 59 60.. code-block:: text 61 62 # for python 3.x 63 $ brew install python3 64 65If you use an installer for your Python, then you can skip to the section 66:ref:`installing_unix`. 67 68 69.. _if-you-don-t-yet-have-a-python-interpreter-unix: 70 71If You Don't Yet Have a Python Interpreter (UNIX) 72~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 73 74If your system doesn't have a Python interpreter, and you're on UNIX, you can 75either install Python using your operating system's package manager *or* you 76can install Python from source fairly easily on any UNIX system that has 77development tools. 78 79.. seealso:: See the official Python documentation :ref:`Using Python on Unix 80 platforms <python:using-on-unix>` for full details. 81 82 83.. index:: 84 pair: install; Python (from package, Windows) 85 86.. _if-you-don-t-yet-have-a-python-interpreter-windows: 87 88If You Don't Yet Have a Python Interpreter (Windows) 89~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 90 91If your Windows system doesn't have a Python interpreter, you'll need to 92install it by downloading a Python 3.x-series interpreter executable from 93`python.org's download section <https://www.python.org/downloads/>`_ (the files 94labeled "Windows Installer"). Once you've downloaded it, double click on the 95executable, and select appropriate options during the installation process. To 96standardize this documentation, we used the GUI installer and selected the 97following options: 98 99- Screen 1: Install Python 3.x.x (32- or 64-bit) 100 - Check "Install launcher for all users (recommended)" 101 - Check "Add Python 3.x to PATH" 102 - Click "Customize installation" 103- Screen 2: Optional Features 104 - Check all options 105 - Click "Next" 106- Screen 3: Advanced Options 107 - Check all options 108 - Customize install location: "C:\\Python3x", where "x" is the minor 109 version of Python 110 - Click "Next" 111 112You might also need to download and install the Python for Windows extensions. 113 114.. seealso:: See the official Python documentation :ref:`Using Python on 115 Windows <python:using-on-windows>` for full details. 116 117.. seealso:: Download and install the `Python for Windows extensions 118 <https://sourceforge.net/projects/pywin32/files/pywin32/>`_. Carefully read 119 the README.txt file at the end of the list of builds, and follow its 120 directions. Make sure you get the proper 32- or 64-bit build and Python 121 version. 122 123.. seealso:: `Python launcher for Windows 124 <https://docs.python.org/3/using/windows.html#launcher>`_ provides a command 125 ``py`` that allows users to run any installed version of Python. 126 127.. warning:: 128 129 After you install Python on Windows, you might need to add the 130 ``c:\Python3x`` directory to your environment's ``Path``, where ``x`` is the 131 minor version of installed Python, in order to make it possible to invoke 132 Python from a command prompt by typing ``python``. To do so, right click 133 ``My Computer``, select ``Properties`` --> ``Advanced Tab`` --> 134 ``Environment Variables``, and add that directory to the end of the ``Path`` 135 environment variable. 136 137 .. seealso:: See `Configuring Python (on Windows) 138 <https://docs.python.org/3/using/windows.html#configuring-python>`_ for 139 full details. 140 141 142.. index:: 143 single: requirements for installing packages 144 145.. _requirements-for-installing-packages: 146 147Requirements for Installing Packages 148------------------------------------ 149 150Use :term:`pip` for installing packages and ``python3 -m venv env`` for 151creating a virtual environment. A virtual environment is a semi-isolated Python 152environment that allows packages to be installed for use by a particular 153application, rather than being installed system wide. 154 155.. seealso:: See the Python Packaging Authority's (PyPA) documention 156 `Requirements for Installing Packages 157 <https://packaging.python.org/en/latest/installing/#requirements-for-installing-packages>`_ 158 for full details. 159 160 161.. index:: 162 single: installing on UNIX 163 single: installing on Mac OS X 164 165.. _installing_unix: 166 167Installing :app:`Pyramid` on a UNIX System 168------------------------------------------ 169 170After installing Python as described previously in :ref:`for-mac-os-x-users` or 171:ref:`if-you-don-t-yet-have-a-python-interpreter-unix`, and satisfying the 172:ref:`requirements-for-installing-packages`, you can now install Pyramid. 173 174#. Make a :term:`virtual environment` workspace: 175 176 .. code-block:: bash 177 178 $ export VENV=~/env 179 $ python3 -m venv $VENV 180 181 You can either follow the use of the environment variable ``$VENV``, or 182 replace it with the root directory of the virtual environment. If you choose 183 the former approach, ensure that ``$VENV`` is an absolute path. In the 184 latter case, the ``export`` command can be skipped. 185 186#. (Optional) Consider using ``$VENV/bin/activate`` to make your shell 187 environment wired to use the virtual environment. 188 189#. Use ``pip`` to get :app:`Pyramid` and its direct dependencies installed: 190 191 .. parsed-literal:: 192 193 $ $VENV/bin/pip install "pyramid==\ |release|\ " 194 195 196.. index:: 197 single: installing on Windows 198 199.. _installing_windows: 200 201Installing :app:`Pyramid` on a Windows System 202--------------------------------------------- 203 204After installing Python as described previously in 205:ref:`if-you-don-t-yet-have-a-python-interpreter-windows`, and satisfying the 206:ref:`requirements-for-installing-packages`, you can now install Pyramid. 207 208#. Make a :term:`virtual environment` workspace: 209 210 .. code-block:: doscon 211 212 c:\> set VENV=c:\env 213 # replace "x" with your minor version of Python 3 214 c:\> c:\Python3x\python -m venv %VENV% 215 c:\> cd %VENV% 216 217 You can either follow the use of the environment variable ``%VENV%``, or 218 replace it with the root directory of the virtual environment. If you choose 219 the former approach, ensure that ``%VENV%`` is an absolute path. In the 220 latter case, the ``set`` command can be skipped. 221 222#. (Optional) Consider using ``%VENV%\Scripts\activate.bat`` to make your shell 223 environment wired to use the virtual environment. 224 225#. Use ``pip`` to get :app:`Pyramid` and its direct dependencies installed: 226 227 .. parsed-literal:: 228 229 c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ " 230 231 232What Gets Installed 233------------------- 234 235When you install :app:`Pyramid`, various libraries such as WebOb, PasteDeploy, 236and others are installed. 237 238Additionally, as chronicled in :ref:`project_narr`, scaffolds will be 239registered, which make it easy to start a new :app:`Pyramid` project. 240