.. _install-label:

.. warning::
    These installation instructions are pending the release of the first version of eXSpy.
    In the meantime, you will need to install the development version, see instructions
    below.

Installation
************

To install eXSpy, you have the following options (independent of the operating system you use):

1. eXSpy is included in the `HyperSpy Bundle <https://hyperspy.org/hyperspy-bundle/>`_,
   a standalone program that includes a python distribution and all relevant libraries
   (recommended if you do not use *python* for anything else).
2. :ref:`conda` (recommended if you are also working with other *python* packages).
3. :ref:`pip`.
4. Installing the development version from `GitHub <https://github.com/hyperspy/exspy/>`_.
   Refer to the appropriate section in the :external+hyperspy:ref:`HyperSpy user guide
   <install-dev>` (replacing ``hyperspy`` by ``exspy``).


.. _conda:

Installation using conda
========================

Follow these 3 steps to install eXSpy using **conda** and start using it.

1. Creating a conda environment
-------------------------------

eXSpy requires Python 3 and ``conda`` -- we suggest using the Python 3 version
of `Miniforge <https://conda-forge.org/miniforge/>`_.

We recommend creating a new environment for the eXSpy package (or installing
it in the :external+hyperspy:ref:`HyperSpy <anaconda-install>`
environment, if you have one already). To create a new environment:

1. Load the miniforge prompt.
2. Run the following command:

.. code-block:: bash

    (base) conda create -n exspy -y


2. Installing the package in the new environment
------------------------------------------------

Now activate the eXSpy environment and install the package from ``conda-forge``:

.. code-block:: bash

    (base) conda activate exspy
    (exspy) conda install -c conda-forge exspy -y

Required dependencies will be installed automatically.

Installation is completed! To start using it, check the next section.

.. Note::

   If you run into trouble, check the more detailed documentation in the
   :external+hyperspy:ref:`HyperSpy user guide <anaconda-install>`.


3. Getting Started
------------------

To get started using eXSpy, especially if you are unfamiliar with Python, we
recommend using `Jupyter notebooks <https://jupyter.org/>`_. Having installed
eXSpy as above, a Jupyter notebook can be installed and opened using the following commands
entered into an anaconda prompt (from scratch):

.. code-block:: bash

    (base) conda activate exspy
    (exspy) conda install -c conda-forge jupyterlab -y
    (exspy) jupyter lab


.. _pip:

Installation using pip
======================

Alternatively, you can also find eXSpy in the `Python Package Index (PyPI) <https://pypi.org>`_
and install it using (requires ``pip``):

.. code-block:: bash

    pip install exspy

Required dependencies will be installed automatically.


Updating the package
====================

Using **conda**:

.. code-block:: bash

    conda update exspy -c conda-forge

Using **pip**:

.. code-block:: bash

    pip install exspy --upgrade

.. Note::

    If you want to be notified about new releases, please *Watch (Releases only)* the `eXSpy repository
    on GitHub <https://github.com/hyperspy/exspy/>`_ (requires a GitHub account).