Installation Guide for macOS#

This guide walks you through installing SpectroChemPy on macOS, step by step. No previous experience with the command line is needed: every command can be copied and pasted in a terminal, the window where commands are typed (see the tip below to open one).

Choosing an Installation Method#

Three installation methods are described below, each based on a different package manager (the tool that installs Python packages). Pick one and follow only its tab, from the first step to the last. The steps of one tab do not apply to the others.

  • uv (recommended): the simplest choice if you are new to Python. uv also downloads Python for you.

  • conda / mamba: choose it if you already use Miniforge, Anaconda or conda environments, or if you also want other scientific tools from conda-forge.

  • pip and venv: uses a Python that you install yourself (from python.org or Homebrew).

Two folders are involved, and it is good practice to keep them separate:

  • the environment, named scpy, which contains Python, SpectroChemPy and its dependencies. You never need to open or modify it. With uv and venv, this guide puts it in ~/scpy (~ is your home folder); with conda / mamba, Miniforge stores it in its own folder.

  • your working folder, which contains your data, scripts and notebooks. It can be any folder you like, for instance a spectrochempy folder in your Documents. Below, it is written <yourWorkingFolder>: replace it with the full path of your folder (for instance /Users/<yourName>/Documents/spectrochempy). To get this path without typing it, select the folder in the Finder, then right-click while holding Option and choose “Copy … as Pathname”.

Warning

Do not create the environment in a folder synchronized with the cloud (iCloud Drive, OneDrive, Google Drive, Dropbox…): it contains thousands of files, which slows down the synchronization and can break the environment. iCloud may synchronize the Documents and Desktop folders. Your working folder, on the other hand, can be synchronized.

Tip

To open a terminal, press Cmd+Space, type Terminal and press Enter. To paste a command in it, press Cmd+V, then press Enter.

Step-by-step Installation#

1. Install uv. Open a terminal and run:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then close the terminal and open a new one. Other ways to install uv (Homebrew, pipx…) are listed in uv’s installation guide.

2. Create and activate the environment in ~/scpy (uv downloads Python if needed):

uv venv ~/scpy --python 3.13
source ~/scpy/bin/activate

The prompt now starts with (scpy).

3. Install SpectroChemPy:

uv pip install spectrochempy

Optional: JupyterLab. The tutorials of this documentation are notebooks. To run them, beginners are advised to install JupyterLab in the same environment:

uv pip install jupyterlab

4. Create a shortcut command. It opens your working folder with the scpy environment already active, so you do not have to type the activation commands each time. Run the following line once, after replacing <yourWorkingFolder> with the path of your working folder (keep the quotes). The terminal of macOS uses the zsh shell, which reads its settings from ~/.zshrc:

echo 'alias scpy="cd \"<yourWorkingFolder>\" && source ~/scpy/bin/activate"' >> ~/.zshrc

5. Check the installation. Close the terminal, open a new one and type scpy: the prompt starts with (scpy) and you are in your working folder. Start IPython and import SpectroChemPy:

scpy
ipython
In [1]: import spectrochempy as scp

Type exit to leave IPython. If you installed JupyterLab, type jupyter lab: JupyterLab opens in your browser, in your working folder. From now on, open a terminal and type scpy each time you work with SpectroChemPy.

If something goes wrong

  • uv: command not found: the terminal was opened before uv was installed. Close it and open a new one.

  • A virtual environment already exists: the environment was already created. To start again from scratch, add --clear to the uv venv command.

  • scpy: command not found: the terminal was not reopened after adding the alias. If echo $SHELL prints /bin/bash (older macOS accounts), add the alias to ~/.bash_profile instead of ~/.zshrc.

  • Otherwise, see Getting Help.

Next Steps#

Proceed to the Guides to start using SpectroChemPy.

Note

If you encounter any issues, see Getting Help for support options.