Start here

Setup

Goal: a working Moonfield install, on your operating system, with you understanding what each step did.

Time: 20–40 minutes the first time.

If a step fails, do not skip it. Go to Getting Unstuck or open a Discussion. A broken environment will make every later lesson confusing in ways that look like astronomy problems but are not.

What we are about to do

The same five steps on every platform:

clone → enter repo → create venv → activate → install → doctor → first command

In plain words:

1. Clone: copy this project from GitHub onto your computer
2. Enter: move your terminal into that copy
3. Create a venv: make a private Python workspace just for this project
4. Activate: tell your terminal to use that workspace
5. Install: put Moonfield into it
6. Doctor: check it all worked

Step 0: open a terminal

A terminal is a window where you type commands instead of clicking. That is the whole idea. It is not a hacker tool and there is nothing you can break by typing the commands in this guide.

You will see a prompt, some text ending in > or $ or %. That means it is waiting for you. When this guide shows a command, type it and press Enter.

A note on WSL. Windows Subsystem for Linux gives you a real Linux environment inside Windows. It is genuinely nice, and if you already have it, use it and follow the Linux instructions. If you do not have it, do not install it just for this. PowerShell works completely. Adding a whole second operating system before your first lesson is not a good trade.

Step 1: check for Python

python3 --version

Windows PowerShell users: use python --version instead. Windows usually does not have the python3 name.

You want 3.10 or newer:

Python 3.12.3

Step 2: check for Git

git --version

Expected: something like git version 2.43.0.

Step 3: clone the repository

git clone https://github.com/Protonmatter/moonfield.git
cd moonfield

The first line downloads a copy. The second moves your terminal into it. From here on, every command assumes you are inside the moonfield folder.

Check you are in the right place:

ls          # Windows PowerShell: dir

You should see README.md, pyproject.toml, src, docs, tests.

cd moonfield              # if it is in your home folder
cd ~/projects/moonfield   # if you put it somewhere else

Step 4: create a virtual environment

python3 -m venv .venv      # Windows PowerShell: python -m venv .venv

Nothing visible happens. That is correct.

What did that do, and why?

A virtual environment is a private Python workspace for one project. It is a folder (here, .venv) containing its own copy of Python and its own place to put packages.

Without one, every package you install goes into one shared pile for your whole computer. Two projects wanting different versions of the same thing will fight, and the loser breaks. With one, each project gets its own pile and they cannot interfere.

The .venv folder is disposable. If your environment ever gets into a state you do not understand, delete it and make a new one. Nothing of yours lives in there. This is covered in Resetting your environment.

Step 5: activate it

This is the step people forget, so if something stops working later, check this first.

Your prompt changes to show (.venv) at the start:

(.venv) you@computer:~/moonfield$

That prefix is how you know it worked. No prefix means not activated.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Step 6: install Moonfield

pip install -e .

The -e means "editable": it links to the source rather than copying it, so if you change the code (and you will, because that is the point), your changes take effect immediately without reinstalling.

The . means "the project in this folder".

Expect a few lines ending in something like:

Successfully installed moonfield-0.1.0

Moonfield has no runtime dependencies. Nothing else gets downloaded. That is deliberate: it means this step almost cannot fail, and it means every formula in the project is one you can go and read.

Step 7: check it worked

moonfield doctor

This is Moonfield's self-check. It reports your Python version, whether your virtual environment is active, your timezone, the current UTC time, your saved location, and it runs the phase engine once to prove the maths works.

It ends with either:

Result: everything essential is working.

or a list of PROBLEM: lines, each with a fix.

What doctor does not tell you. It confirms your computer knows what timezone it is in and can do the arithmetic. It cannot confirm your clock is actually set correctly; nothing on your own machine can check its own clock. If your predictions are consistently a few minutes off, that is worth investigating. See Time and place.

Step 8: tell it where you are

moonfield config set-location --lat 51.4779 --lon -0.0015 \
    --name "Greenwich" --timezone Europe/London

Replace those numbers with your own.

• Latitude: north positive, south negative. Sydney is -33.8688.
• Longitude: east positive, west negative. New York is -74.006.

The most common mistake in this whole project is a longitude sign. If your results are wildly wrong later (the Sun rising at midnight, the Moon on the wrong side of the sky), check this first. Places west of Greenwich (the Americas, western Europe, west Africa) have negative longitude.

To find your coordinates: open any map website, right-click where you are, and it will show you two numbers. The first is latitude, the second longitude.

Timezone names look like Europe/Lisbon, America/Chicago, Australia/Sydney, Africa/Nairobi. You can leave --timezone off and it will use your computer's setting.

Check it:

moonfield config show

You are done

moonfield phase

If you see a Moon, you have a working install.

Next: Your first command, which explains what that output actually means.

Quick reference

Every new terminal session:

cd moonfield                     # go to the project
source .venv/bin/activate        # Windows: .venv\Scripts\Activate.ps1
moonfield phase                  # do astronomy

To leave the virtual environment: deactivate.

Checkpoint

• I can open a terminal on my system
• I know how to check my Python version
• I know what a virtual environment is and why it exists
• I can activate mine, and I know I must do it each session
• moonfield doctor reports everything working
• I have saved my location, with the right longitude sign
• I know doctor checks configuration, not clock accuracy
• I know where to go when I get stuck

Getting stuck?

• Getting Unstuck: by symptom
• Resetting your environment: start clean
• Windows-specific problems
• macOS-specific problems
• Linux and WSL problems
• Discussions: ask a human

Go deeper

• What a virtual environment really is
• What pip install -e . actually does