This document will guide you through setting up and using your machine for success in CS 307.
Setup
Update Your Operating System
Before you start, you should probably be sure operating system (OS) is reasonably up to date. However, don’t let this step hold you back, just realize that if your aren’t up-to-date, things could go wrong. In this past, we’ve discovered that some students have not applied operating system updates in years! This is terrible from a security perspective, but could also prevent some software from operating properly.
Before applying OS updates, make sure you can be plugged into power and without access to your machine for up to an hour. Also, as there is a small chance that things go wrong during updates, be sure you have any and all important files backed-up. You have a backup plan, right?
Install VSCode
First, you’ll need to install Visual Studio Code, which we will usually abbreviate as VSCode.
If you have previously downloaded VSCode, no-need to re-install. However, if any updates are available, we recommend applying them.
On macOS, it is important that you properly install VSCode. We have often found that students do not do so correctly, mostly because Microsoft distributes VSCode in a somewhat odd manner compared to other macOS software.
After downloading VSCode, you must place it in your Applications folder. To check if that was the case for an existing installation, open VSCode, then right click its icon in your Dock. Select Options > Show in Finder. If installed correctly, this will open your Applications folder.
If not, you should quit VSCode. Be sure to quit, not simply close the window. Then, delete anything related to VSCode from your Downloads folder. Next, re-download VSCode. Take the file that is downloaded, and drag it to your Applications folder. Open that file from the Applications folder to launch VSCode.
Create CS 307 Directory
Create a directory (folder) for CS 307. You can create it anywhere you’ like, but your Desktop is fine. You can name it anything you want, but something like cs307 is recommended.
Next, open this folder in VSCode. There are various ways to do so, but selecting File > Open Folder... is the most straightforward.
You will use this folder to collect all things CS 307. Opening a folder rather than an individual file will provide several advantages when working in VSCode for CS 307.
Install uv
Rather than install Python, we will install uv. You must install uv even if you have previously installed Python.
The installation instructions are slightly different for macOS and Windows.
In VSCode, open a terminal and run the following command:
curl -LsSf https://astral.sh/uv/install.sh | sh
In VSCode, open a terminal. Verify that the terminal is using the powershell shell. Run the following command:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
With either OS, after installing uv, restart your terminal. The easiest way to do so is to fully quit then reopen VSCode. When you relaunch VSCode, be sure to also reopen your CS 307 folder if VSCode does not do so automatically. We wil always assume you have this folder open when running commands in the future.
Setup Python
We will manage Python through uv. As a result, no need to install Python! Thankfully, uv will automatically take care of that for us.
Instead, we will create a virtual environment. In doing so, we will specify the exact version of Python needed for CS 307.
With your CS 307 folder open in VSCode, run the following in (VSCode’s) terminal to create an environment with Python 3.12:
uv venv --python 3.12.8 --python-preference only-managed
In VSCode’s Explorer, you should see a folder named .venv.
If you use version control such as git, together with GitHub, be sure to add .venv to your .gitignore. The .venv folder contains an entire Python installation, which would be annoying to check-in to version control and push to GitHub.
With a virtual environment created, you should optionally activate it. This step is not strictly necessary, but will help avoid conflicts with conda.
Run the following command:
source .venv/bin/activate
Run the following command:
.venv\Scripts\activate
Install Python Packages
To install Python packages, we will use uv, and a list of packages to be installed. First, download requirements.txt and place that file in your CS 307 folder.
If you click the above link, most modern web browsers will display the content rather than download the file. To download the file, right click the link then use Save As. By default, it should save as requirements.txt, but be sure to not change the file extension. If you instead open the link in a browser and then save, some browsers will save it as a webpage rather than a text file, which will cause issues.
Next, verify that conda is not currently active. To be certain conda does not interfere, run:
conda deactivate
If you do not have conda installed, this will result in an error such as command not found, but that means everything will work as expected, and you are not burdened by conda.
If you do have conda installed, your shell prompt will likely be prefixed by (base). After running conda deactivate, (base) should be removed from your prompt.
Then, in VSCode, with your CS 307 folder open, bring up a terminal and run:
uv pip install -r requirements.txt
To verify installation, run:
uv pip freeze
This should display a long list of packages and their versions. If so, you’re all set.
Install VSCode Extensions
Install two VSCode Extensions:
Many incorrectly assume that Jupyter is a Python specific tool. Very much not the case.
“Project Jupyter’s name is a reference to the three core programming languages supported by Jupyter, which are Julia, Python and R.”
Install Quarto
Use of Quarto is required to properly render lab reports in CS 307. To use Quarto together with Jupyter and VSCode, you’ll need to install both Quarto CLI, as well as the Quarto VSCode Extension.
Check Jupyter
Now, let’s test that everything is working properly.
Create a new Jupyter Notebook in VSCode. In the top right, click Select Kernel. If you see .venv (Python 3.12.8), select it! If not, chose Select Another Kernel, then Python Environments..., then .venv (Python 3.12.8).
Now, in a Python cell, place the following and run it:
from sklearn.datasets import load_wine
from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import accuracy_score
wine = load_wine()
X, y = wine.data, wine.target
X_train, X_test, y_train, y_test = train_test_split(
X,
y,
test_size=0.5,
random_state=42,
)
clf = RandomForestClassifier(
n_estimators=5,
random_state=42,
)
clf.fit(X_train, y_train)
y_pred = clf.predict(X_test)
accuracy = accuracy_score(y_test, y_pred)
print(f"Accuracy: {accuracy:.4f}")
If your output matches the above, you’re all set!
The first time you run code after using the virtual environment as the Jupyter kernel, this code my take 30 seconds to a minute to run. After the first time, that initial delay will not persist.
Check Quarto
Save the notebook you were just working on as something like temp.ipynb. We’ll delete it when we are done. Now we need to render it, using Quarto, not Jupyter.
To do so, in a terminal, run:
quarto preview temp.ipynb
Replace temp.ipynb with the name of whatever file you want to render.
Alternatively, You can also use the menu (with Code, Markdown, Run All, etc) at the top of the notebook. Click the three dots on the far right, then click Preview.
Do not use Export. This uses Jupyter, not Quarto. Doing so on labs will not be accepted.
Notice that a file named temp.html was created. You should see it in the Explorer panel. If VSCode did not do so automatically, open this file in a web browser to see the result.
To finish up, clean up your folder by deleting:
test.ipynbtest.htmltest_files