Installation Guide

Note

PyAMARES requires Python 3.8 or newer. We recommend using Python 3.11 or newer.

Warning

If you require Python 3.6 or 3.7 compatibility for older systems, please use the legacy2025 branch (version 0.3.29):

python -m pip install git+https://github.com/HawkMRS/pyAMARES.git@legacy2025#egg=pyAMARES

The legacy branch is maintained for critical bug fixes only. For the latest features and improvements, we strongly recommend upgrading to Python 3.11 or newer.

PIP installation

It is recommended to create a Python environment using Anaconda or Miniconda.

PyAMARES requires Python 3.8 or higher. To create a new conda environment with Python 3.12, follow these steps:

Open a terminal window.
Run the command:
```
conda create -n env_name python=3.12
```
Here, replace env_name with the desired name for your PyAMARES environment.
After the environment has been created, activate it by running:
```
conda activate env_name
```
Now, you can proceed to install PyAMARES using the pip command. See the next tab Use pip.

After creating the Python environment using conda, PyAMARES can be installed with the pip command directly:

conda activate env_name
pip install pyamares

If you do not have system-wide installation permissions:

python3 -m pip install pyamares --user

To install the most recent version of pyAMARES from source code, use:

pip install git+https://github.com/HawkMRS/pyAMARES

Now, you have successfully installed pyAMARES in the Python environment env_name. In the future, always activate this environment with:

conda activate env_name

Note

Setting up Jupyter notebook (optional)

If you do not already have Jupyter notebook installed in another conda environment, you can first activate your environment with conda activate my_env and then install the classic Jupyter notebook with:

pip install notebook

Alternatively, you can install the more modern JupyterLab with:

pip install jupyterlab

If you are an experienced user who already has Jupyter Notebook installed under another conda environment, you can add the environment where pyAMARES was just installed (env_name) as one of the kernels of your Jupyter Notebook with the display name Python (env_name) (or any other name you choose):

pip install ipykernel
python -m ipykernel install --user --name env_name --display-name "Python (env_name)"

Google Colab is a free Google service that allows users to write and execute Python entirely in the cloud. You just need a Google Account to launch a Jupyter notebook on Colab.

To use pyAMARES on Colab, simply create a new notebook, and in a new cell, type:

!pip install pyamares

After installation, execute the following in another new cell:

import pyAMARES

You can then start using pyAMARES online or proceed to the “Getting Started” section.

Note

Please note that the development version might be unstable, so it is primarily for testing and development purposes.

If you want to install the latest development version of pyAMARES directly from GitHub, use the following command:

conda activate env_name
python -m pip install git+https://github.com/HawkMRS/pyAMARES.git@dev#egg=pyAMARES

This command tells pip to install the package directly from the dev branch of the Github repository.

If you want to install the web interface of pyAMARES locally, you can do so by running the following command:

conda activate env_name
python -m pip install git+https://github.com/HawkMRS/pyAMARES.git@dev#egg=pyAMARES  # install pyAMARES first
python -m pip install git+https://github.com/HawkMRS/pyAMARES.git@gui#egg=pyAMARES[streamlit]  # install web interface

After installation, you can run one of these commands to launch the web interface locally:

# Launch pyAMARES and automatically open in your default browser
streamlit run https://raw.githubusercontent.com/HawkMRS/pyAMARES/refs/heads/gui/pyAMARES/script/amaresfit_gui.py

# Launch the web server only (access via http://localhost:8501 in your browser)
streamlit run https://raw.githubusercontent.com/HawkMRS/pyAMARES/refs/heads/gui/pyAMARES/script/amaresfit_gui.py --server.headless true

For more information about running Streamlit apps, please visit the Streamlit documentation.

Update Installed pyAMARES

PyAMARES is under active development. You can update the installed version of pyAMARES using the following command:

pip install --upgrade pyAMARES

Alternatively, you can install the development version directly from GitHub as previously mentioned:

python -m pip install git+https://github.com/HawkMRS/pyAMARES.git@dev#egg=pyAMARES

Please refer to the installation details in the Install Dev Version Directly from GitHub section above.