============ Installation

Prerequisites

• Python interpreter
• Adjust your path
• Packaging tools

Python interpreter ^^^^^^^^^^^^^^^^^^

Install Python for your operating system. On Windows and macOS this is usually necessary. Most Linux distributions come with Python pre-installed. Consult the official Python documentation <https://docs.python.org/3/using/index.html>_ for details.

You can install the Python binaries from python.org <https://www.python.org/downloads/>. Alternatively on macOS, you can use the homebrew <http://brew.sh/> package manager.

.. code-block:: bash

brew install python3

Adjust your path ^^^^^^^^^^^^^^^^

Ensure that your bin folder is on your path for your platform. Typically ~/.local/ for UNIX and macOS, or %APPDATA%\Python on Windows. (See the Python documentation for site.USER_BASE <https://docs.python.org/3/library/site.html#site.USER_BASE>_ for full details.)

UNIX and macOS """"""""""""""

For bash shells, add the following to your .bash_profile (adjust for other shells):

.. code-block:: bash

# Add ~/.local/ to PATH
export PATH=$HOME/.local/bin:$PATH

Remember to load changes with source ~/.bash_profile or open a new shell session.

Windows """""""

Ensure the directory where cookiecutter will be installed is in your environment's Path in order to make it possible to invoke it 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 %APPDATA%\Python\Python3x\Scripts, where you have your version of Python instead of Python3x.

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.

Unix on Windows

You may also install Windows Subsystem for Linux <https://msdn.microsoft.com/en-us/commandline/wsl/install-win10>_ or GNU utilities for Win32 <http://unxutils.sourceforge.net>_ to use Unix commands on Windows.

Packaging tools ^^^^^^^^^^^^^^^

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

Install cookiecutter

At the command line:

.. code-block:: bash

python3 -m pip install --user cookiecutter

Or, if you do not have pip:

.. code-block:: bash

easy_install --user cookiecutter

Though, pip is recommended, easy_install is deprecated.

Or, if you are using conda, first add conda-forge to your channels:

.. code-block:: bash

conda config --add channels conda-forge

Once the conda-forge channel has been enabled, cookiecutter can be installed with:

.. code-block:: bash

conda install cookiecutter

Alternate installations

Homebrew (Mac OS X only):

.. code-block:: bash

brew install cookiecutter

Void Linux:

.. code-block:: bash

xbps-install cookiecutter

Pipx (Linux, OSX and Windows):

.. code-block:: bash

pipx install cookiecutter

Upgrading

from 0.6.4 to 0.7.0 or greater ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

First, read the release notes <https://github.com/cookiecutter/cookiecutter/releases>_ in detail. There are a lot of major changes. The big ones are:

• Cookiecutter no longer deletes the cloned repo after generating a project.
• Cloned repos are saved into ~/.cookiecutters/.
• You can optionally create a ~/.cookiecutterrc config file.

Or with pip:

.. code-block:: bash

python3 -m pip install --upgrade cookiecutter

Upgrade Cookiecutter either with easy_install (deprecated):

.. code-block:: bash

easy_install --upgrade cookiecutter

Then you should be good to go.