Installation & Setup

EasyUtilities is a cross-platform Python library compatible with Python 3.11 through 3.13.

To install and set up EasyUtilities, we recommend using Pixi, a modern package manager for Windows, macOS, and Linux.

Main benefits of using Pixi

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 EasyUtilities using Pixi.

Installing Pixi

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

Setting up EasyUtilities 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 easyutilities
cd easyutilities
```
Set the Python version for the Pixi environment (e.g., 3.13):
```
pixi add python=3.13
```
Add EasyUtilities to the Pixi environment from PyPI:
```
pixi add --pypi easyutilities
```

Add a Pixi task to run EasyUtilities commands easily:

pixi task add easyutilities "python -m easyutilities"

Updating Pixi and EasyUtilities

To update all packages in the Pixi environment, including EasyUtilities:
```
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 EasyUtilities 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

Installing from PyPI

EasyUtilities is available on PyPI (Python Package Index) and can be installed using pip. To do so, use the following command:

pip install easyutilities

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

pip install 'easyutilities==1.0.3'

To upgrade to the latest version:

pip install --upgrade easyutilities

To upgrade to the latest version and force reinstallation of all dependencies (useful if files are corrupted):

pip install --upgrade --force-reinstall easyutilities

To check the installed version:

pip show easyutilities

Installing from GitHub alternative

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

To install EasyUtilities from the develop branch of GitHub, for example:

pip install git+https://github.com/easyscience/utils@develop

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

pip install 'easyutilities[dev] @ git+https://github.com/easyscience/utils@develop'