| commit | author | age | ||
| 189c6e | 1 | .. _installing_chapter: |
| CM | 2 | |
| fd5ae9 | 3 | Installing :app:`Pyramid` |
| 6ce54f | 4 | ========================= |
| 102d19 | 5 | |
| ec1bbf | 6 | .. note:: |
| SP | 7 | |
| 74cf44 | 8 | This installation guide emphasizes the use of Python 3.4 and greater for |
| SP | 9 | simplicity. |
| ec1bbf | 10 | |
| SP | 11 | |
| 8c56ae | 12 | .. index:: |
| c5f24b | 13 | single: install preparation |
| 8c56ae | 14 | |
| ec1bbf | 15 | Before You Install Pyramid |
| SP | 16 | -------------------------- |
| 102d19 | 17 | |
| ec1bbf | 18 | Install Python version 3.4 or greater for your operating system, and satisfy |
| SP | 19 | the :ref:`requirements-for-installing-packages`, as described in |
| 20 | the following sections. | |
| 102d19 | 21 | |
| 9ec2d6 | 22 | .. sidebar:: Python Versions |
| 102d19 | 23 | |
| a5c810 | 24 | As of this writing, :app:`Pyramid` is tested against Python 2.7, |
| c8a5e0 | 25 | Python 3.4, Python 3.5, Python 3.6, and PyPy. |
| 096532 | 26 | |
| bb0f9b | 27 | :app:`Pyramid` is known to run on all popular UNIX-like systems such as Linux, |
| ec1bbf | 28 | Mac OS X, and FreeBSD, as well as on Windows platforms. It is also known to |
| SP | 29 | run on :term:`PyPy` (1.9+). |
| 4ad6d4 | 30 | |
| ec1bbf | 31 | :app:`Pyramid` installation does not require the compilation of any C code. |
| SP | 32 | However, some :app:`Pyramid` dependencies may attempt to build binary |
| 33 | extensions from C code for performance speed ups. If a compiler or Python | |
| 34 | headers are unavailable, the dependency will fall back to using pure Python | |
| 35 | instead. | |
| 096532 | 36 | |
| ec1bbf | 37 | .. note:: |
| SP | 38 | |
| 39 | If you see any warnings or errors related to failing to compile the binary | |
| 40 | extensions, in most cases you may safely ignore those errors. If you wish to | |
| 41 | use the binary extensions, please verify that you have a functioning | |
| 42 | compiler and the Python header files installed for your operating system. | |
| 08bf6f | 43 | |
| 44bbbc | 44 | |
| SP | 45 | .. _for-mac-os-x-users: |
| 46 | ||
| 7c4700 | 47 | For Mac OS X Users |
| SP | 48 | ~~~~~~~~~~~~~~~~~~ |
| 49 | ||
| 1cbf35 | 50 | Python comes pre-installed on Mac OS X, but due to Apple's release cycle, it is |
| SP | 51 | often out of date. Unless you have a need for a specific earlier version, it is |
| ec1bbf | 52 | recommended to install the latest 3.x version of Python. |
| 7c4700 | 53 | |
| 0bc888 | 54 | You can install the latest version of Python for Mac OS X from the binaries on |
| 109792 | 55 | `python.org <https://www.python.org/downloads/mac-osx/>`_. |
| 7c4700 | 56 | |
| 7b1612 | 57 | Alternatively, you can use the `homebrew <https://brew.sh/>`_ package manager. |
| 7c4700 | 58 | |
| f0398e | 59 | .. code-block:: text |
| NZ | 60 | |
| ec1bbf | 61 | # for python 3.x |
| f0398e | 62 | $ brew install python3 |
| 7c4700 | 63 | |
| bb0f9b | 64 | If you use an installer for your Python, then you can skip to the section |
| SP | 65 | :ref:`installing_unix`. |
| 7c4700 | 66 | |
| 44bbbc | 67 | |
| SP | 68 | .. _if-you-don-t-yet-have-a-python-interpreter-unix: |
| 69 | ||
| 6ce54f | 70 | If You Don't Yet Have a Python Interpreter (UNIX) |
| dfc6e5 | 71 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| CM | 72 | |
| bb0f9b | 73 | If your system doesn't have a Python interpreter, and you're on UNIX, you can |
| SP | 74 | either install Python using your operating system's package manager *or* you |
| 75 | can install Python from source fairly easily on any UNIX system that has | |
| 76 | development tools. | |
| dfc6e5 | 77 | |
| ec1bbf | 78 | .. seealso:: See the official Python documentation :ref:`Using Python on Unix |
| SP | 79 | platforms <python:using-on-unix>` for full details. |
| 6ce1e0 | 80 | |
| CM | 81 | |
| 82 | .. index:: | |
| 83 | pair: install; Python (from package, Windows) | |
| ec1bbf | 84 | |
| SP | 85 | .. _if-you-don-t-yet-have-a-python-interpreter-windows: |
| dfc6e5 | 86 | |
| 6ce54f | 87 | If You Don't Yet Have a Python Interpreter (Windows) |
| dfc6e5 | 88 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| CM | 89 | |
| bb0f9b | 90 | If your Windows system doesn't have a Python interpreter, you'll need to |
| ec1bbf | 91 | install it by downloading a Python 3.x-series interpreter executable from |
| 1cb30e | 92 | `python.org's download section <https://www.python.org/downloads/>`_ (the files |
| bb0f9b | 93 | labeled "Windows Installer"). Once you've downloaded it, double click on the |
| 9cd5b6 | 94 | executable and select appropriate options during the installation process. To |
| 108121 | 95 | standardize this documentation, we used the GUI installer and selected the |
| SP | 96 | following options: |
| 97 | ||
| 98 | - Screen 1: Install Python 3.x.x (32- or 64-bit) | |
| 9cd5b6 | 99 | - Check "Install launcher for all users (recommended)". |
| SP | 100 | - Check "Add Python 3.x to PATH". |
| 101 | - Click "Install Now". | |
| 102 | - Screen 2: User Account Control | |
| 103 | - Click "Yes". | |
| dfc6e5 | 104 | |
| ec1bbf | 105 | .. seealso:: See the official Python documentation :ref:`Using Python on |
| 43549f | 106 | Windows <python:using-on-windows>` for full details. |
| ec1bbf | 107 | |
| 9cd5b6 | 108 | .. seealso:: You might also need to download and install the `Python for |
| SP | 109 | Windows extensions |
| 1cb30e | 110 | <https://sourceforge.net/projects/pywin32/files/pywin32/>`_. Carefully read |
| ec1bbf | 111 | the README.txt file at the end of the list of builds, and follow its |
| SP | 112 | directions. Make sure you get the proper 32- or 64-bit build and Python |
| 113 | version. | |
| 114 | ||
| 108121 | 115 | .. seealso:: `Python launcher for Windows |
| SP | 116 | <https://docs.python.org/3/using/windows.html#launcher>`_ provides a command |
| 117 | ``py`` that allows users to run any installed version of Python. | |
| 118 | ||
| 9cd5b6 | 119 | .. warning:: After you install Python on Windows, you might need to add the |
| SP | 120 | directory where Python and other programs—such as pip, setuptools, and |
| 121 | cookiecutter—are installed to your environment's ``Path``. This will make it | |
| 122 | possible to invoke them from a command prompt. | |
| c5f24b | 123 | |
| 9cd5b6 | 124 | To do so, search for "Environment Variables" on your computer (on Windows |
| 7ed8e2 | 125 | 10, it is under ``System Properties`` --> ``Advanced``) and add that |
| SP | 126 | directory to the ``Path`` environment variable, using the GUI to edit path |
| 127 | segments. | |
| 128 | ||
| 129 | Example segments should look like | |
| 9cd5b6 | 130 | ``C:\Users\<username>\AppData\Local\Programs\Python3x-32``, where you have |
| 7ed8e2 | 131 | your username instead of ``<username>``, and your version of Python and |
| SP | 132 | whether it is 32- or 64-bit. Additionally ensure you have the path segment |
| 133 | ending with ``\Scripts``, i.e., | |
| 134 | ``C:\Users\<username>\AppData\Local\Programs\Python3x-32\Scripts``, and for | |
| 135 | user-installed Python programs, ``%APPDATA%\Python\Python3x\Scripts``. | |
| 136 | ||
| 137 | You may need to restart your command prompt session to load the environment | |
| 138 | variables. | |
| ec1bbf | 139 | |
| SP | 140 | .. seealso:: See `Configuring Python (on Windows) |
| 141 | <https://docs.python.org/3/using/windows.html#configuring-python>`_ for | |
| 142 | full details. | |
| 143 | ||
| 144 | ||
| 145 | .. index:: | |
| 146 | single: requirements for installing packages | |
| 147 | ||
| 148 | .. _requirements-for-installing-packages: | |
| 149 | ||
| 150 | Requirements for Installing Packages | |
| 151 | ------------------------------------ | |
| 152 | ||
| d60369 | 153 | Use :term:`pip` for installing packages and ``python3 -m venv env`` for |
| SP | 154 | creating a virtual environment. A virtual environment is a semi-isolated Python |
| ec1bbf | 155 | environment that allows packages to be installed for use by a particular |
| SP | 156 | application, rather than being installed system wide. |
| 157 | ||
| 158 | .. seealso:: See the Python Packaging Authority's (PyPA) documention | |
| 159 | `Requirements for Installing Packages | |
| 7b1612 | 160 | <https://packaging.python.org/tutorials/installing-packages/#requirements-for-installing-packages>`_ |
| ec1bbf | 161 | for full details. |
| SP | 162 | |
| c5f24b | 163 | |
| 8c56ae | 164 | .. index:: |
| c5f24b | 165 | single: installing on UNIX |
| ec1bbf | 166 | single: installing on Mac OS X |
| 8c56ae | 167 | |
| 9ec2d6 | 168 | .. _installing_unix: |
| CM | 169 | |
| fd5ae9 | 170 | Installing :app:`Pyramid` on a UNIX System |
| 6ce54f | 171 | ------------------------------------------ |
| 189c6e | 172 | |
| ec1bbf | 173 | After installing Python as described previously in :ref:`for-mac-os-x-users` or |
| SP | 174 | :ref:`if-you-don-t-yet-have-a-python-interpreter-unix`, and satisfying the |
| 175 | :ref:`requirements-for-installing-packages`, you can now install Pyramid. | |
| 102d19 | 176 | |
| d67566 | 177 | #. Make a :term:`virtual environment` workspace: |
| eab66f | 178 | |
| ec1bbf | 179 | .. code-block:: bash |
| db0969 | 180 | |
| ec1bbf | 181 | $ export VENV=~/env |
| d60369 | 182 | $ python3 -m venv $VENV |
| db0969 | 183 | |
| ec1bbf | 184 | You can either follow the use of the environment variable ``$VENV``, or |
| SP | 185 | replace it with the root directory of the virtual environment. If you choose |
| 186 | the former approach, ensure that ``$VENV`` is an absolute path. In the | |
| 187 | latter case, the ``export`` command can be skipped. | |
| db0969 | 188 | |
| ec1bbf | 189 | #. (Optional) Consider using ``$VENV/bin/activate`` to make your shell |
| SP | 190 | environment wired to use the virtual environment. |
| 7bc20e | 191 | |
| ec1bbf | 192 | #. Use ``pip`` to get :app:`Pyramid` and its direct dependencies installed: |
| db0969 | 193 | |
| ec1bbf | 194 | .. parsed-literal:: |
| eab66f | 195 | |
| ec1bbf | 196 | $ $VENV/bin/pip install "pyramid==\ |release|\ " |
| eab66f | 197 | |
| 21f2b6 | 198 | .. index:: |
| SP | 199 | single: $VENV/bin/pip vs. source bin/activate |
| 200 | ||
| 201 | .. _venv-bin-pip-vs-source-bin-activate: | |
| 202 | ||
| 203 | .. note:: Why use ``$VENV/bin/pip`` instead of ``source bin/activate``, then | |
| 204 | ``pip``? | |
| 205 | ||
| 781cf1 | 206 | ``$VENV/bin/pip`` clearly specifies that ``pip`` is run from within the |
| SP | 207 | virtual environment and not at the system level. |
| 21f2b6 | 208 | |
| 57ce7b | 209 | ``activate`` makes changes to the user's shell environment which can often be convenient. However, in the context of long-form documentation, environment configuration can easily be forgotten. By keeping each snippet explicit we can reduce copy / paste errors by users in which commands are executed against the wrong Python environment. Also, ``deactivate`` might not correctly restore previous shell environment variables. Avoiding ``activate`` keeps the environment more reproducible. |
| 781cf1 | 210 | |
| SP | 211 | Although using ``source bin/activate``, then ``pip``, requires fewer key |
| 212 | strokes to issue commands once invoked, there are other things to consider. | |
| 213 | Michael F. Lamb (datagrok) presents a summary in `Virtualenv's bin/activate | |
| 214 | is Doing It Wrong <https://gist.github.com/datagrok/2199506>`_. | |
| 215 | ||
| 216 | Ultimately we prefer to keep things clear and simple, so we use | |
| 217 | ``$VENV/bin/pip``. | |
| 21f2b6 | 218 | |
| 08bf6f | 219 | |
| 8c56ae | 220 | .. index:: |
| c5f24b | 221 | single: installing on Windows |
| 9ec2d6 | 222 | |
| CM | 223 | .. _installing_windows: |
| 9d9370 | 224 | |
| fd5ae9 | 225 | Installing :app:`Pyramid` on a Windows System |
| 6ce54f | 226 | --------------------------------------------- |
| 859f9d | 227 | |
| ec1bbf | 228 | After installing Python as described previously in |
| SP | 229 | :ref:`if-you-don-t-yet-have-a-python-interpreter-windows`, and satisfying the |
| 230 | :ref:`requirements-for-installing-packages`, you can now install Pyramid. | |
| eab66f | 231 | |
| d67566 | 232 | #. Make a :term:`virtual environment` workspace: |
| eab66f | 233 | |
| a651b3 | 234 | .. code-block:: doscon |
| eab66f | 235 | |
| 7ed8e2 | 236 | c:\> cd \ |
| f73f0e | 237 | c:\> set VENV=c:\env |
| 9cd5b6 | 238 | c:\> python -m venv %VENV% |
| 108121 | 239 | c:\> cd %VENV% |
| eab66f | 240 | |
| ec1bbf | 241 | You can either follow the use of the environment variable ``%VENV%``, or |
| SP | 242 | replace it with the root directory of the virtual environment. If you choose |
| 243 | the former approach, ensure that ``%VENV%`` is an absolute path. In the | |
| 244 | latter case, the ``set`` command can be skipped. | |
| eab66f | 245 | |
| f73f0e | 246 | #. (Optional) Consider using ``%VENV%\Scripts\activate.bat`` to make your shell |
| ec1bbf | 247 | environment wired to use the virtual environment. |
| eab66f | 248 | |
| ec1bbf | 249 | #. Use ``pip`` to get :app:`Pyramid` and its direct dependencies installed: |
| 859f9d | 250 | |
| 232310 | 251 | .. parsed-literal:: |
| 65bb52 | 252 | |
| 108121 | 253 | c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ " |
| ec1bbf | 254 | |
| 21f2b6 | 255 | .. note:: See the note above for :ref:`Why use $VENV/bin/pip instead of source |
| SP | 256 | bin/activate, then pip <venv-bin-pip-vs-source-bin-activate>`. |
| 257 | ||
| 9ec2d6 | 258 | |
| 9d9370 | 259 | What Gets Installed |
| e4ed8f | 260 | ------------------- |
| 9d9370 | 261 | |
| ec1bbf | 262 | When you install :app:`Pyramid`, various libraries such as WebOb, PasteDeploy, |
| SP | 263 | and others are installed. |
| 9d9370 | 264 | |
| 6b3f9e | 265 | Additionally, as chronicled in :ref:`project_narr`, :term:`cookiecutter`\ s will be |
| SP | 266 | used, which make it easy to start a new :app:`Pyramid` project. |
