🙋‍♂️ Tech Support

Introduction
Environments and Package Managers
Replicating the Gradescope Environment
Working on Assignments

Introduction

In the real world, you’ll be expected to set up and maintain a Python environment locally – that is, on your own computer – and so that’s what we’ll have you do in this course as well.

There has been a lot written about how to set up a Python environment, so we won’t reinvent the wheel. This page will only be a summary; Google will be your main resource. But always feel free to come to a staff member’s office hours if you have a question about setting up your environment, using Git, or similar — we’re here to help.

Environments and Package Managers

For this class, the software you’ll need includes Python 3.12, uv, a few specific Python packages, Git, and a text editor.

Gradescope has an environment which it uses to autograde your work. You can think of an environment as a combination of a Python version and specific versions of Python packages that is isolated from the rest of your computer. In practice, developers create different environments for different projects, so that they can use different versions of packages in different projects.

We’re going to have you replicate the environment Gradescope has on your computer. The reason for this is so that your code behaves the same when you submit it to Gradescope as it does when you work on it on your computer. For example, our Gradescope environment uses numpy version 2.1.1; if you install a different version of numpy on your computer, for example, you might see different results than Gradescope sees.

How do you install packages, then? pip is a common choice, but even though it’s widely used, it lacks built-in support for creating isolated environments. This limitation makes it challenging to maintain version consistency and avoid conflicts between packages. Consequently, we do not recommend using pip at all for environment management, as it may inadvertently introduce incompatible package versions.

uv, on the other hand, is a powerful tool that not only installs packages but also manages environments effortlessly. It allows you to create isolated environments and ensures compatibility among the packages within those environments.

Replicating the Gradescope Environment

Below, we’re going to walk you through how to create the same environment that Gradescope uses.

Step 0 (Windows only): Windows Subsystem for Linux

You can skip this step if you are not using a Windows machine, or if you already have WSL set up.

If you are using a Windows machine, we will use the Windows Subsystem for Linux (WSL) to give you a Linux terminal. This isn’t absolutely necessary to follow along with the course, but it will make the rest of the setup much easier. We will not support or document other setups for the course.

Open PowerShell and run:
```
wsl --install
```
This will install the latest version of Ubuntu.
For more details, see the Microsoft documentation.
Now, launch the Ubuntu terminal by making a new tab in the Windows Terminal and selecting “Ubuntu” from the dropdown, or by going to your Start Menu and opening “Ubuntu”. Ubuntu is a Linux distribution that is installed by default with WSL.
Now, install git. In your Ubuntu terminal, run:
```
sudo apt-get update
sudo apt-get install git
```
For more details, see the Git documentation for WSL.

All future setup steps will assume you are either using the Ubuntu, macOS, or Linux terminal.

Step 1: Install `uv`

Run the uv installer. To do this, open your Terminal and run:

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

After this step, check that uv is available by running the uv command. If this command doesn’t work, you may need to start a new terminal window and close your old one.

$ uv
An extremely fast Python package manager.

Usage: uv [OPTIONS] <COMMAND>

...

You should see a help menu listing the available commands.

Step 2: Clone the course repository

Clone the course GitHub repository, which not only contains the course materials, but also a pyproject.toml file with the necessary details to configure your environment:

git clone https://github.com/dsc-courses/dsc259r-2026-wi

This will create a folder called dsc259r-2026-wi. If you look at the pyproject.toml file inside, you’ll see that it contains a specific Python version (python=3.12) along with specific package versions (like pandas==2.2.3 and requests==2.32.3, for example).

Step 3: Sync the environment

To sync the environment, navigate to the cloned repository folder (cd dsc259r-2026-wi), then in your Terminal, run:

uv sync

You should see that uv will download and install the packages we need for the course.

Step 4: Check that everything is working

To check that everything is working, you can run the following command in your Terminal:

uv run otter --version
# should print info about the Python version, and display a line showing that the
# otter-grader version is 3.1.4

Working on Assignments

The setup instructions above only need to be run once.

Now, you can open Jupyter Lab, by using the uv run jupyter lab command in your Terminal. You can also use VSCode to open notebooks by setting the Python interpreter to the one installed by uv.

Using Git

All of our course materials, including your assignments, are hosted on GitHub in this Git repository.

Git is a version control system. In short, it is used to keep track of the history of a project. With Git, you can go back in time to any previous version of your project, or even work on two different versions (or "branches") in parallel and "merge" them together at some point in the future. We'll stick to using the basic features of Git in this course.

There are Git GUIs, and you can use them for this class. You can also use the command-line version of Git. We’ve already used git above to clone the course repository.

Moving forward, to bring in the latest version of the repository, in your local repository, run:

git pull

This will not overwrite your work. In fact, Git is designed to make it very difficult to lose work (although it's still possible!).

Merge Conflicts

You might face issues when using git pull regarding merge issues and branches. This is caused by files being updated on your side while we are also changing the Git repository by pushing new assignments on our side. Here are some steps you can follow to resolve them:

NOTE: Whenever working with GitHub pulls, merges, etc., it’s a good idea to save your important work locally so that if you accidentally overwrite your files you still have the work saved. Save your work locally before following the steps below.

git status shows the current state of your Git working directory and staging area. It’s a good sanity check to start with. You will probably see your project and lab files that you have worked on.
git add . will add all your files to be ready to commit.
git commit -m "some message of your choice" will commit the files, with some description in the quotations. This can be whatever you want, it won’t matter.

At this stage, if you git pull, it should work. You should double-check that you have new files, as well as that your old files are unchanged. If they are changed then you should be able to just copy-paste from your local backup. If this does not work then you may have merge conflicts, follow the next steps:

git checkout --ours [FILENAME] will tell git that whenever a conflict occurs in [FILENAME] to keep your version. Run this for each file with a conflict.
git add [FILENAME] to mark each file with a conflict as resolved.
git commit to commit the changes.

Choosing a Text Editor or IDE

In this class, you will need to use a combination of editors for doing your assignments: The Python files should be developed with a text editor (for syntax highlighting and running doctests) and the data/results should be analyzed/presented in Jupyter Notebooks. Below is an incomplete list of IDEs you might want to try. For more information about them, feel free to ask the course staff.

If you’re curious, the course instructor uses VSCode to edit .py files and the JupyterLab environment to edit notebooks.

The JupyterLab text editor: see below. Can be used to edit both notebooks and .py files.
VSCode: Microsoft Visual Studio Code. Currently very popular, and can also be used to edit both notebooks and .py files.
sublime: A favorite text editor of hackers, famous for its multiple cursors. A good, general-purpose choice.
PyCharm (IntelliJ): Those who feel at home coding Java. Can only work locally.
(neo)vim: lightweight, productive text-editor that runs in the terminal. Very popular among developers, but also has a very steep learning curve.

Using VSCode to Run Jupyter Notebooks

Many students like to use VSCode to edit Jupyter Notebooks. If that’s you, then you’ll need to make sure to activate your environment within your notebook in VSCode. Here’s how to do that.

Open a Juypter Notebook in VSCode.
Click “Select Kernel” in the top right corner of the window.

Click “Python: Select Interpreter” in the toolbar that appears in the middle.

Finally, click “.venv (Python 3.13.2)”.