Setup guide · Your own computer
Follow these steps the first time you run a course notebook on a laptop or home computer. Steps 1 to 4 happen once per computer. Steps 5 to 8 are the routine for every lab.
Part A · Once per computer
Most of the time here goes to step 2, while conda downloads packages.
If you downloaded the repository from GitHub as a ZIP file, extract it first: on Windows, right-click the file and choose Extract All; on macOS, double-click it. Move the extracted folder somewhere easy to find, such as Documents.
The course folder is the one that contains environment.yml and the data, notebooks, and src folders. If extracting created a folder of the same name inside another one, use the inner folder. A folder cloned with Git or GitHub Desktop is ready as it is.
Open Anaconda Prompt from the Start menu on Windows, or Terminal on macOS. The prompt usually begins with (base). Then run:
cd path/to/course-folder
conda env create -f environment.yml
conda env listReplace path/to/course-folder with the location of your course folder. The quickest way: type cd and a space, drag the course folder from File Explorer (Windows) or Finder (macOS) into the window, and press Enter.
conda then downloads the packages listed in environment.yml and builds an environment named earth-course, which can take several minutes. When it finishes, conda env list shows earth-course.
Created earth-course on this computer before? conda will report that it already exists; go on to step 3. You do not need the data download scripts for lab work, because the cleaned datasets every notebook reads are already in data/processed/.
Open VS Code and press Ctrl+Shift+X (Cmd+Shift+X on macOS) to open the Extensions view. Search for and install Python and Jupyter, and check that Microsoft is the publisher of both.
VS Code may add companion extensions, such as Pylance, on its own. That is expected.
Choose File → Open Folder… and select the course folder from step 1, the one that contains environment.yml. The Explorer sidebar on the left then lists data, notebooks, src, and the other course folders.
When VS Code asks Do you trust the authors of the files in this folder?, choose Yes, I trust the authors. VS Code runs notebook cells only in folders you trust.
Part B · Every lab
Repeat these steps each time you start or continue a lab.
Lab notebooks belong in notebooks/individual_labs/ or notebooks/group_labs/ inside the course folder. The first code cell finds the course data by searching upward from the notebook's own location for a folder named data, so a notebook left in Downloads or on the Desktop cannot find it.
A notebook you download from the Course materials section lands in your Downloads folder. Move it into the matching subfolder before you open it.
Continuing a lab you started on another computer? Copy your in-progress .ipynb file to this computer (for example, through cloud storage, email, or a USB drive) and put it in the same subfolder.
earth-course kernelIn the Explorer sidebar, open the notebooks folder and click your .ipynb file.
Click Select Kernel in the top-right corner of the notebook, choose Python Environments…, and pick earth-course from the list.
The top-right corner now shows earth-course. VS Code usually remembers this choice for the notebook, but glance at that corner each time you open one.
Click the run button (▷) to the left of the first code cell, or click inside the cell and press Shift+Enter. The output should look like this:
Project root: C:\Users\you\Documents\earth-environment-computing-course
Processed data folder exists: TrueProject root should be your course folder. If the second line reads False, stop and return to step 5 before you run anything else.
Save with Ctrl+S (Cmd+S on macOS). VS Code does not save on its own unless you turn on File → Auto Save.
Before you submit, click Restart in the notebook toolbar, then Run All. Every cell should run from top to bottom without an error; this is the same Restart and Run All check the course uses all semester.
Troubleshooting
Find the message you see, then try the fix next to it.
conda is not recognized, or command not foundOn Windows, open Anaconda Prompt from the Start menu; PowerShell, Command Prompt, and the VS Code terminal often cannot find conda. On macOS, quit and reopen Terminal after installing Anaconda.
environment.ymlThe prompt is not in the course folder yet. Run dir (Windows) or ls (macOS) and confirm that environment.yml is listed. On Windows, if the folder is on a drive other than C:, use cd /d followed by the path.
earth-course is missing from the kernel listQuit and reopen VS Code so it detects the new environment, then repeat step 6. If the name is still missing, run conda env list to check that step 2 finished without an error.
No module named 'pandas', or a prompt to install ipykernelThe notebook is using a different Python environment. Switch the kernel to earth-course (step 6), which already includes pandas, NumPy, Matplotlib, and ipykernel. Then click Restart and run the notebook from the first cell.
No module named 'earthcourse'Run the path cell first (step 7). It adds the course folder's src directory, where earthcourse lives, to Python's search path. If the error remains, the notebook is outside the course folder (step 5).
Processed data folder exists: False, or FileNotFoundErrorThe notebook is outside the course folder. Move it into the matching notebooks/ subfolder (step 5), reopen it from the VS Code Explorer, and click Restart before you run the path cell again.
The folder is not trusted yet. Click Restricted Mode at the left end of the status bar, at the bottom of the window, and trust the folder.
Copy the last lines of the error message and bring them to studio, or include them in an email to your instructor. Meanwhile, if you installed the full Anaconda Distribution, you can pick its base environment in step 6; it already includes every package these labs use.
A crash with no Python error message points to the Python environment on this computer. If the same notebook runs on another computer, the notebook itself is fine. Work through these checks in order.
Check the kernel. The name at the top right of the notebook should read earth-course. If it shows base, another Python version, or a Microsoft Store Python, switch it (step 6).
Test the environment outside Jupyter. Run the two lines below in Anaconda Prompt or Terminal. If they print OK and create test_plot.png, the environment works and the problem is in Jupyter. If they show an error, that message is the clue to fix.
conda activate earth-course
python -c "import pandas, matplotlib; matplotlib.use('Agg'); import matplotlib.pyplot as plt; plt.plot([1, 2, 3]); plt.savefig('test_plot.png'); print('OK', pandas.__version__, matplotlib.__version__)"Read the Jupyter log. Click View Jupyter log in the crash message, or open the Output panel and choose Jupyter. The last lines usually name the actual error.
Rebuild the environment. In Anaconda Prompt or Terminal, go to the course folder (as in step 2), then remove earth-course and create it again. Reopen VS Code, select earth-course (step 6), and click Restart.
conda deactivate
conda env remove -n earth-course
conda env create -f environment.ymlAvoid installing extra packages into earth-course with pip; mixing pip and conda installs is one common cause of crashes.
Still crashing? Bring the last lines of the Jupyter log to studio, or include them in an email to your instructor. Until it is fixed, you can keep working on any computer where the course environment runs.
Alternative
The commands in the course hub's setup section open the same notebooks in JupyterLab, in your web browser, with the same earth-course environment. From Anaconda Prompt or Terminal:
cd path/to/course-folder
conda activate earth-course
jupyter labIn JupyterLab, the check before you submit is Kernel → Restart Kernel and Run All Cells…. Still stuck? Bring evidence to the next studio session: the full error message, the step you were on, and a screenshot that shows the kernel name in the notebook's top-right corner.
← Back to course setup