Installation & Setup

EasyDiffraction is a cross-platform Python library compatible with Python 3.11 through 3.14.

EasyDiffraction is a cross-platform Python library compatible with Python 3.11 through 3.13.
Make sure Python is installed on your system before proceeding with the installation.

Environment Setup optional

- **Ease of use**: Pixi simplifies the installation process, making it
  accessible even for users with limited experience in package management.
- **Python version control**: Pixi allows specifying and managing different
  Python versions for each project, ensuring compatibility.
- **Isolated environments**: Pixi creates isolated environments for each
  project, preventing conflicts between different package versions.
- **PyPI and Conda support**: Pixi can install packages from both PyPI and
  Conda repositories, providing access to a wide range of libraries.

An alternative installation method using the traditional pip package manager is also provided.

Installing with Pixi recommended

This section describes the simplest way to set up EasyDiffraction using Pixi.

Installing Pixi

• Install Pixi by following the instructions on the official Pixi Installation Guide.

Setting up EasyDiffraction with Pixi

• Choose a project location (local drive recommended).

  Windows + OneDrive

  We do not recommend creating a Pixi project inside OneDrive or other synced folders.

  By default, Pixi creates the virtual environment inside the project directory (in .pixi/). On Windows, synced folders such as OneDrive may cause file‑system issues (e.g., path-length limitations or restricted link operations), which can lead to unexpected install errors or environments being recreated.

  Instead, create your project in a local directory on your drive where you have full write permissions.

• Initialize a new Pixi project and navigate into it:

  pixi init easydiffraction
  cd easydiffraction
  

• Set the Python version for the Pixi environment (e.g., 3.14):

  pixi add python=3.14
  

• Add EasyDiffraction to the Pixi environment from PyPI:

  pixi add --pypi easydiffraction
  

• Add a Pixi task to run EasyDiffraction commands easily:

  pixi task add easydiffraction "python -m easydiffraction"
  

Updating Pixi and EasyDiffraction

• To update all packages in the Pixi environment, including EasyDiffraction:

  pixi update
  

• To update Pixi itself to the latest version:

  pixi self-update
  

Uninstalling Pixi

• Follow the official Pixi Guide.

Classical Installation

This section describes how to install EasyDiffraction using the traditional method with pip. It is assumed that you are familiar with Python package management and virtual environments.

Environment Setup optional

We recommend using a virtual environment to isolate dependencies and avoid conflicts with system-wide packages. If any issues arise, you can simply delete and recreate the environment.

Creating and Activating a Virtual Environment:

• Create a new virtual environment:

  python3 -m venv venv
  

• Activate the environment:

  macOS Linux Windows

  . venv/bin/activate
  

  . venv/bin/activate
  

  . venv/Scripts/activate      # Windows with Unix-like shells
  .\venv\Scripts\activate.bat  # Windows with CMD
  .\venv\Scripts\activate.ps1  # Windows with PowerShell
  

• The terminal should now show (venv), indicating that the virtual environment is active.

Deactivating and Removing the Virtual Environment:

• Exit the environment:

  deactivate
  

• If this environment is no longer needed, delete it:

  macOS Linux Windows

  rm -rf venv
  

  rm -rf venv
  

  rmdir /s /q venv
  

Installation Guide

Installing from PyPI recommended

EasyDiffraction is available on PyPI (Python Package Index) and can be installed using pip. We strongly recommend installing it within a virtual environment, as described in the Environment Setup section.

We recommend installing the latest release of EasyDiffraction with the visualization extras, which include optional dependencies used for simplified visualization of charts and tables. This can be especially useful for running the Jupyter Notebook examples. To do so, use the following command:

pip install 'easydiffraction[visualization]'

If only the core functionality is needed, the library can be installed simply with:

pip install easydiffraction

To install a specific version of EasyDiffraction, e.g., 1.0.3:

pip install 'easydiffraction==1.0.3'

To upgrade to the latest version:

pip install --upgrade --force-reinstall easydiffraction

To check the installed version:

pip show easydiffraction

Installing from GitHub

Installing unreleased versions is generally not recommended but may be useful for testing.

To install EasyDiffraction from, e.g., the develop branch of GitHub:

pip install git+https://github.com/easyscience/diffraction-lib@develop

To include extra dependencies (e.g., visualization):

pip install 'easydiffraction[visualization] @ git+https://github.com/easyscience/diffraction-lib@develop'

How to Run Tutorials

EasyDiffraction includes a collection of Jupyter Notebook examples that demonstrate key functionality. These tutorials serve as step-by-step guides to help users understand the diffraction data analysis workflow.

They are available as static HTML pages in the Tutorials section. You can also run them interactively in two ways:

• Run Locally – Download the notebook via the Download button and run it on your computer.
• Run Online – Use the Open in Google Colab button to run the tutorial directly in your browser (no setup required).

Note

You can also download all Jupyter notebooks at once as a zip archive from the EasyDiffraction Releases.

Run Tutorials Locally

To run tutorials locally, install Jupyter Notebook or JupyterLab. Here are the steps to follow in the case of Jupyter Notebook:

• Install Jupyter Notebook and IPython kernel:

  pip install notebook ipykernel
  

• Add the virtual environment as a Jupyter kernel

  python -m ipykernel install --user --name=venv --display-name "EasyDiffraction Python kernel"
  

• Download the EasyDiffraction tutorials from GitHub Releases:

  python -m easydiffraction fetch-tutorials
  

• Launch the Jupyter Notebook server in the examples/ directory:

  jupyter notebook tutorials/
  

• In your web browser, go to:

  http://localhost:8888/
  

• Open one of the *.ipynb files and select the EasyDiffraction Python kernel to get started.

Run Tutorials via Google Colab

Google Colab lets you run Jupyter Notebooks in the cloud without any local installation.

To use Google Colab:

• Ensure you have a Google account.
• Go to the Tutorials section.
• Click the Open in Google Colab button on any tutorial.

This is the fastest way to start experimenting with EasyDiffraction, without setting up Python on your system.

Installing with Pixi alternative

Pixi is a modern package and environment manager for Python and Conda-compatible packages. It simplifies dependency management, environment isolation, and reproducibility.

The following simple steps provide an alternative setup method for EasyDiffraction using Pixi, replacing the traditional virtual environment approach.

• Install Pixi by following the instructions on the official Pixi Installation Guide.
• Create a dedicated directory for the EasyDiffraction and navigate into it:

  mkdir easydiffraction
  cd easydiffraction
  

• Download the pixi configuration file for EasyDiffraction:

  curlwget

  curl -LO https://raw.githubusercontent.com/easyscience/diffraction-lib/master/pixi.toml
  

  wget https://raw.githubusercontent.com/easyscience/diffraction-lib/master/pixi.toml
  

• Create the environment defined in pixi.toml and install all necessary dependencies:

  pixi install
  

• Fetch the EasyDiffraction tutorials to the tutorials/ directory:

  pixi run easydiffraction fetch-tutorials
  

• Start JupyterLab in the tutorials/ directory to access the notebooks:

  pixi run jupyter lab tutorials/
  

• Your web browser should open automatically. Click on one of the *.ipynb files and select the Python (Pixi) kernel to get started.