.. _installing_chapter:

Installing :app:`Pyramid`
=========================

.. note::

    This installation guide emphasizes the use of Python 3.6 and greater for
    simplicity.


.. index::
   single: install preparation

Before You Install Pyramid
--------------------------

Install Python version 3.6 or greater for your operating system, and satisfy
the :ref:`requirements-for-installing-packages`, as described in
the following sections.

.. sidebar:: Python Versions

    As of this writing, :app:`Pyramid` is tested against Python 3.6, 3.7, 3.8, and 3.9 and PyPy3.

:app:`Pyramid` is known to run on all popular Unix-like systems such as Linux,
macOS, and FreeBSD, as well as on Windows platforms.  It is also known to
run on :term:`PyPy` (1.9+).

:app:`Pyramid` installation does not require the compilation of any C code.
However, some :app:`Pyramid` dependencies may attempt to build binary
extensions from C code for performance speed ups. If a compiler or Python
headers are unavailable, the dependency will fall back to using pure Python
instead.

.. note::

   If you see any warnings or errors related to failing to compile the binary
   extensions, in most cases you may safely ignore those errors. If you wish to
   use the binary extensions, please verify that you have a functioning
   compiler and the Python header files installed for your operating system.


.. _for-macos-users:

For macOS Users
~~~~~~~~~~~~~~~

Python comes pre-installed on macOS, but due to Apple's release cycle, it is
often out of date. Unless you have a need for a specific earlier version, it is
recommended to install the latest 3.x version of Python.

You can install the latest version of Python for macOS from the binaries on
`python.org <https://www.python.org/downloads/mac-osx/>`_.

Alternatively, you can use the `homebrew <https://brew.sh/>`_ package manager.

.. code-block:: bash

    # for python 3.x
    brew install python3

If you use an installer for your Python, then you can skip to the section
:ref:`installing_unix`.


.. _if-you-don-t-yet-have-a-python-interpreter-unix:

If You Don't Yet Have a Python Interpreter (Unix)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If your system doesn't have a Python interpreter, and you're on Unix, you can
either install Python using your operating system's package manager *or* you
can install Python from source fairly easily on any Unix system that has
development tools.

.. seealso:: See the official Python documentation :ref:`Using Python on Unix
   platforms <python:using-on-unix>` for full details.


.. index::
   pair: install; Python (from package, Windows)

.. _if-you-don-t-yet-have-a-python-interpreter-windows:

If You Don't Yet Have a Python Interpreter (Windows)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If your Windows system doesn't have a Python interpreter, you'll need to
install it by downloading a Python 3.x-series interpreter executable from
`python.org's download section <https://www.python.org/downloads/>`_ (the files
labeled "Windows Installer").  Once you've downloaded it, double click on the
executable and select appropriate options during the installation process. To
standardize this documentation, we used the GUI installer and selected the
following options:

- Screen 1: Install Python 3.x.x (32- or 64-bit)
    - Check "Install launcher for all users (recommended)".
    - Check "Add Python 3.x to PATH".
    - Click "Install Now".
- Screen 2: User Account Control
    - Click "Yes".

.. seealso:: See the official Python documentation :ref:`Using Python on
   Windows <python:using-on-windows>` for full details.

.. seealso:: You might also need to download and install the `Python for
   Windows extensions
   <https://sourceforge.net/projects/pywin32/files/pywin32/>`_. Carefully read
   the README.txt file at the end of the list of builds, and follow its
   directions. Make sure you get the proper 32- or 64-bit build and Python
   version.

.. seealso:: `Python launcher for Windows
   <https://docs.python.org/3/using/windows.html#launcher>`_ provides a command
   ``py`` that allows users to run any installed version of Python.

.. warning:: After you install Python on Windows, you might need to add the
   directory where Python and other programs—such as pip, :term:`Setuptools`, and
   cookiecutter—are installed to your environment's ``Path``. This will make it
   possible to invoke them from a command prompt.

   To do so, search for "Environment Variables" on your computer (on Windows
   10, it is under ``System Properties`` --> ``Advanced``) and add that
   directory to the ``Path`` environment variable, using the GUI to edit path
   segments.

   Example segments should look like
   ``C:\Users\<username>\AppData\Local\Programs\Python3x-32``, where you have
   your username instead of ``<username>``, and your version of Python and
   whether it is 32- or 64-bit. Additionally ensure you have the path segment
   ending with ``\Scripts``, i.e.,
   ``C:\Users\<username>\AppData\Local\Programs\Python3x-32\Scripts``, and for
   user-installed Python programs, ``%APPDATA%\Python\Python3x\Scripts``.

   You may need to restart your command prompt session to load the environment
   variables.

   .. seealso:: See `Configuring Python (on Windows)
      <https://docs.python.org/3/using/windows.html#configuring-python>`_ for
      full details.


.. index::
   single: requirements for installing packages

.. _requirements-for-installing-packages:

Requirements for Installing Packages
------------------------------------

Use :term:`pip` for installing packages and ``python3 -m venv env`` for
creating a virtual environment. A virtual environment is a semi-isolated Python
environment that allows packages to be installed for use by a particular
application, rather than being installed system wide.

.. seealso:: See the Python Packaging Authority's (PyPA) documention
   `Requirements for Installing Packages
   <https://packaging.python.org/tutorials/installing-packages/#requirements-for-installing-packages>`_
   for full details.


.. index::
   single: installing on Unix
   single: installing on macOS

.. _installing_unix:

Installing :app:`Pyramid` on a Unix System
------------------------------------------

After installing Python as described previously in :ref:`for-macos-users` or
:ref:`if-you-don-t-yet-have-a-python-interpreter-unix`, and satisfying the
:ref:`requirements-for-installing-packages`, you can now install Pyramid.

#. Make a :term:`virtual environment` workspace:

   .. code-block:: bash

       export VENV=~/env
       python3 -m venv $VENV

   You can either follow the use of the environment variable ``$VENV``, or
   replace it with the root directory of the virtual environment. If you choose
   the former approach, ensure that ``$VENV`` is an absolute path. In the
   latter case, the ``export`` command can be skipped.

#. (Optional) Consider using ``$VENV/bin/activate`` to make your shell
   environment wired to use the virtual environment.

#. Use ``pip`` to get :app:`Pyramid` and its direct dependencies installed:

   .. parsed-literal::

       $VENV/bin/pip install "pyramid==\ |release|\ "

.. index::
   single: $VENV/bin/pip vs. source bin/activate

.. _venv-bin-pip-vs-source-bin-activate:

.. note:: Why use ``$VENV/bin/pip`` instead of ``source bin/activate``, then
   ``pip``?

   ``$VENV/bin/pip`` clearly specifies that ``pip`` is run from within the
   virtual environment and not at the system level.

   ``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.

   Although using ``source bin/activate``, then ``pip``, requires fewer key
   strokes to issue commands once invoked, there are other things to consider.
   Michael F. Lamb (datagrok) presents a summary in `Virtualenv's bin/activate
   is Doing It Wrong <https://gist.github.com/datagrok/2199506>`_.

   Ultimately we prefer to keep things clear and simple, so we use
   ``$VENV/bin/pip``.


.. index::
   single: installing on Windows

.. _installing_windows:

Installing :app:`Pyramid` on a Windows System
---------------------------------------------

After installing Python as described previously in
:ref:`if-you-don-t-yet-have-a-python-interpreter-windows`, and satisfying the
:ref:`requirements-for-installing-packages`, you can now install Pyramid.

#. Make a :term:`virtual environment` workspace:

   .. code-block:: doscon

       cd \
       set VENV=c:\env
       python -m venv %VENV%
       cd %VENV%

   You can either follow the use of the environment variable ``%VENV%``, or
   replace it with the root directory of the virtual environment. If you choose
   the former approach, ensure that ``%VENV%`` is an absolute path. In the
   latter case, the ``set`` command can be skipped.

#. (Optional) Consider using ``%VENV%\Scripts\activate.bat`` to make your shell
   environment wired to use the virtual environment.

#. Use ``pip`` to get :app:`Pyramid` and its direct dependencies installed:

   .. parsed-literal::

       %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "

.. note:: See the note above for :ref:`Why use $VENV/bin/pip instead of source
   bin/activate, then pip <venv-bin-pip-vs-source-bin-activate>`.


What Gets Installed
-------------------

When you install :app:`Pyramid`, various libraries such as WebOb, PasteDeploy,
and others are installed.

Additionally, as chronicled in :ref:`project_narr`, our :term:`cookiecutter` will be used, which makes it easy to start a new :app:`Pyramid` project.
