Before You Start

If you’ve never installed a Python package from GitHub before, this page is for you. It walks through every piece of software you need on your computer before you follow the Installation instructions, and points you to where each one lives.

If you already have a working Python environment, a GitHub account, and Jupyter installed, skip ahead to Installation.

What you’ll need

To run exo2micro you need four things on your computer:

  1. A terminal application (you already have one — see below).

  2. A GitHub account, so you can download (clone) the code.

  3. A Python installation, so the code can actually run.

  4. JupyterLab (or Jupyter Notebook), to open the interactive GUI notebook.

The rest of this page walks through each one.

Note

Throughout this page, anything shown in a code block (like cd Documents) is a command you type into your terminal and then press Enter. Don’t type the $ or > prompt if your terminal shows one — just the text after it.

1. Opening a terminal

Most of the setup is done by typing commands into a “terminal” — a text-based window where you talk to your computer directly. Every modern computer has one built in.

On macOS:

The app is called Terminal. To open it:

  • Press Cmd + Space to open Spotlight search.

  • Type Terminal and press Enter.

A small window with a text prompt will open. That’s your terminal.

On Windows:

The app is called Windows Terminal (Windows 11) or Command Prompt / PowerShell (Windows 10). The easiest option for following these instructions is to install Windows Terminal if you don’t have it — it’s free from the Microsoft Store. To open it:

  • Click the Start menu.

  • Type Terminal (or PowerShell if Terminal isn’t there) and press Enter.

A window with a text prompt will open. That’s your terminal.

Tip

Keep the terminal window open — you’ll be using it throughout this setup. You can close it when you’re done; the changes you make are permanent.

2. Creating a GitHub account

exo2micro’s code lives on GitHub, a website that hosts open-source software. To download the code, you’ll need a free GitHub account.

  1. Go to https://github.com/signup

  2. Enter an email address, password, and username. (Your username will be public; pick something professional if you plan to share code in the future.)

  3. Verify your email when GitHub sends you a confirmation message.

That’s it — you don’t need to set up any other GitHub features to use exo2micro.

Note

You don’t strictly need a GitHub account just to download exo2micro (the code is public), but having one makes it much easier to report bugs, ask questions, and pull updates when new versions come out. It also means you’ll have git configured properly, which the installation step assumes.

You also need the git command-line tool installed so your terminal can talk to GitHub:

On macOS:

git comes pre-installed on most Macs. To check, type this into your terminal and press Enter:

git --version

If you see something like git version 2.39.0, you’re set. If you see command not found, macOS will pop up a dialog offering to install the “Command Line Developer Tools” — click Install and wait for it to finish (a few minutes).

On Windows:

Download and install Git for Windows from https://git-scm.com/download/win. Accept all the defaults during installation. After it finishes, close and reopen your terminal, then check it worked by typing:

git --version

3. Installing Python

exo2micro is written in Python, so you need a Python installation on your computer. The recommended way to install Python for scientific work is Miniforge, which gives you Python plus conda, a tool that manages scientific Python packages cleanly.

Note

You may already have a Python installation (especially on macOS, which ships with one). We strongly recommend installing Miniforge anyway and using it for exo2micro. Mixing the system Python with scientific packages tends to cause hard-to-debug problems.

On macOS:

  1. Go to https://github.com/conda-forge/miniforge#download

  2. Download the installer for your Mac. If you have an Apple Silicon Mac (M1, M2, M3, M4 — anything from 2020 or later), download Miniforge3-MacOSX-arm64.sh. For older Intel Macs, download Miniforge3-MacOSX-x86_64.sh.

  3. In your terminal, navigate to your Downloads folder and run the installer:

    cd ~/Downloads
bash Miniforge3-MacOSX-arm64.sh

    (Use the filename you actually downloaded.) Press Enter to scroll through the license, type yes to accept, press Enter to confirm the install location, and type yes when it asks whether to initialize Miniforge.

  4. Close and reopen your terminal. This is required — the changes don’t take effect in the window where you ran the installer.

  5. Verify it worked:

    python --version

    You should see something like Python 3.12.7.

On Windows:

  1. Go to https://github.com/conda-forge/miniforge#download

  2. Download Miniforge3-Windows-x86_64.exe.

  3. Double-click the downloaded file to run the installer. Accept the defaults, but on the “Advanced Installation Options” page, check the box that says Add Miniforge3 to my PATH environment variable. (The installer warns against this, but it makes things much easier for you. Ignore the warning.)

  4. Close and reopen your terminal.

  5. Verify it worked:

    python --version

    You should see something like Python 3.12.7.

4. Installing JupyterLab

JupyterLab is the application that lets you open .ipynb notebook files, including the exo2micro interactive GUI. With Python installed, getting JupyterLab is one command.

In your terminal, type:

pip install jupyterlab ipywidgets

Wait for the install to finish (a minute or two). When it’s done, test it by launching JupyterLab:

jupyter lab

Your default web browser will open with the JupyterLab interface. You’ll see a file browser on the left showing whatever folder you launched from.

To stop JupyterLab, go back to the terminal window where you ran jupyter lab and press Ctrl + C. Confirm with y if asked.

Tip

JupyterLab runs in your web browser, but it’s not on the internet — it’s a local server on your own computer. You can use it offline.

You’re ready

Once you have all four pieces working:

  • A terminal you can open

  • A GitHub account and the git command

  • Python (via Miniforge)

  • JupyterLab

…proceed to Installation, which walks through downloading exo2micro itself and installing its dependencies.

If anything on this page didn’t work, see Troubleshooting or open an issue on the GitHub repository.