Setting Up

This guide equips your computer with the essential software environment for Good Enough Coding in Science (GECS). Complete these setup steps before attending Session 1: Collaborating with Git and GitHub.

For deeper background on our editor and terminal environments, explore our reference guides on VS Code and the Terminal.

Checklist

Before attending Session 1, verify that your computer meets the following requirements:

Requirement Verification
Active GitHub account with 2FA or passkey enabled Can sign in at github.com
Visual Studio Code installed with the GECS profile loaded VS Code opens and displays your environment
Git installed with your name and email configured git config user.name outputs your identity
Working shell with uv package manager installed uv --version returns version number
TipPre-Flight Clinic Check

To rapidly verify your local environment (Gates 3 & 4), open the integrated terminal in VS Code and run:

echo "--- Git Identity ---" && git config user.name && git config user.email
echo "--- Tools ---" && code -v && uv --version

If both commands print your details and version numbers without error, you are ready for Session 1!

GitHub Account, Authentication & Privacy

GitHub hosts our course repositories and enables collaborative pull-request workflows.

  1. Sign Up: If you do not have an account, create one at github.com/signup.

  2. Enable Multi-Factor Authentication (2FA) & Passkeys: GitHub requires 2FA for all accounts. We recommend registering a Passkey via your GitHub Settings > Password and authentication. Alternatively, use an authenticator app (such as Google Authenticator or 1Password).

    A passkey is a modern, phishing-resistant credential tied directly to your physical device (using Touch ID, Face ID, Windows Hello, or a security key like YubiKey). Instead of typing passwords and one-time authenticator codes, your device authenticates you with a biometric touch or device PIN.

  3. Hide Your Email Address on GitHub (Recommended): By default, the email address configured in your local Git client is permanently embedded into every commit you create, making it visible to anyone inspecting public repositories. GitHub provides an email privacy option to protect your address from web scrapers and spam:

    • Navigate to GitHub Settings > Emails (github.com/settings/emails).
    • Check Keep my email addresses private. GitHub will generate a private no-reply email address for your account (in the format 12345678+username@users.noreply.github.com or username@users.noreply.github.com).
    • Check Block command line pushes that expose my email. This protects you from accidentally pushing commits with a private or institutional address.
    • Copy your generated ...users.noreply.github.com address—you will use it when configuring your local Git identity in Step 2!

Students and academic researchers can receive free GitHub Pro access through GitHub Education. After signing up, apply at github.com/settings/education/benefits using your institutional email address or proof of affiliation.

Platform Installation

Select your operating system below to configure your development environment:

1. Terminal & Homebrew

macOS provides a UNIX terminal out of the box (Terminal.app in Applications > Utilities) running Zsh.

To manage scientific tools and ensure an up-to-date version of Git, install Homebrew, the de-facto package manager for macOS:

  1. Open Terminal.app.

  2. Run the Homebrew installation command:

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  3. Follow the on-screen instructions. If prompted to add Homebrew to your PATH, copy and run the suggested commands.

  4. Install Git:

    brew install git

Alternative: If running git --version in Terminal prompts you to install the Apple “Command Line Developer Tools”, you can click Install to obtain Apple’s system Git (xcode-select --install).

2. Visual Studio Code

  1. Download Visual Studio Code for macOS from code.visualstudio.com.
  2. Open the downloaded .zip file and drag Visual Studio Code.app into your /Applications folder.
  3. Launch VS Code. Open the Command Palette (Cmd+Shift+P), type Shell Command: Install 'code' command in PATH, and press Enter. This enables launching VS Code from the terminal.

Import the GECS Profile

VS Code profiles quickly bundle recommended settings and extensions for this course.

  1. In VS Code, click the Manage gear icon in the lower-left corner and select Profiles > Import Profile….

  2. Paste the following URL and click Create:

    https://gist.github.com/igorsdub/04f6a1191dde8e09091a1099fe87d5be

  3. Accept any suggested extension installations.

If you encounter network issues importing the profile, open the Extensions view (Cmd+Shift+X) and manually install: - Python (Microsoft) - Data Science Extension Pack (Microsoft) - Ruff (Astral Software)

3. Package Manager: uv

We use uv to manage Python versions and environments reproducibly.

  1. Open the integrated terminal in VS Code (View > Terminal or Ctrl+`).

  2. Install uv:

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

  3. Reload your shell environment:

    source ~/.zshrc

  4. Verify the installation:

    uv --version

4. Git Identity Configuration

Configure Git with your name and email address. If you enabled email privacy in Step 1, use your GitHub-generated no-reply email address:

git config --global user.name "Your Name"
# Use your institutional email, or your private GitHub no-reply address:
git config --global user.email "your.email@oist.jp"
git config --global init.defaultBranch main

If you enabled Keep my email addresses private on GitHub, replace "your.email@oist.jp" with your private address (e.g. "12345678+username@users.noreply.github.com"). Your commits will still show your GitHub avatar and profile without exposing your real email.

1. System Packages & Git

Open your terminal application (Ctrl+Alt+T) and ensure Git and curl are installed:

sudo apt update && sudo apt install -y git curl build-essential

2. Visual Studio Code

  1. Download the .deb installer from code.visualstudio.com and install it, or install via your distribution’s package manager.
  2. Launch VS Code.

Import the GECS Profile

  1. Click the Manage gear icon in the lower-left corner and select Profiles > Import Profile….

  2. Paste the following URL and click Create:

    https://gist.github.com/igorsdub/04f6a1191dde8e09091a1099fe87d5be

  3. Accept any suggested extension installations.

If profile import fails, open the Extensions view (Ctrl+Shift+X) and install: - Python (Microsoft) - Data Science Extension Pack (Microsoft) - Ruff (Astral Software)

3. Package Manager: uv

  1. Open the integrated terminal in VS Code (View > Terminal or Ctrl+`).

  2. Install uv:

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

  3. Reload your shell configuration:

    source ~/.bashrc

  4. Verify the installation:

    uv --version

4. Git Identity Configuration

Configure Git with your name and email address. If you enabled email privacy in Step 1, use your GitHub-generated no-reply email address:

git config --global user.name "Your Name"
# Use your institutional email, or your private GitHub no-reply address:
git config --global user.email "your.email@oist.jp"
git config --global init.defaultBranch main

If you enabled Keep my email addresses private on GitHub, replace "your.email@oist.jp" with your private address (e.g. "12345678+username@users.noreply.github.com").

Windows users will run Linux via the Windows Subsystem for Linux (WSL) with an Ubuntu distribution. All course development happens inside this UNIX environment.

1. Install WSL and Ubuntu

  1. Open the Windows Start Menu, search for PowerShell, right-click it, and select Run as administrator.

  2. Run the WSL installation command:

    wsl --install

  3. Restart your computer when prompted.

  4. After restarting, a terminal window will open to complete the Ubuntu setup. When prompted, enter a UNIX username and password.

  • Use lowercase letters and numbers for your username (e.g., jsmith).
  • When typing your password in the UNIX terminal, no characters or asterisks will appear on screen. Type your password and press Enter.

If WSL fails to install: 1. Ensure Windows 10/11 is updated. 2. In the Start Menu, open Turn Windows features on or off. 3. Check both Windows Subsystem for Linux and Virtual Machine Platform, click OK, and restart. 4. If an error mentions hardware virtualization (VT-x or AMD-V), enable virtualization in your computer’s BIOS/UEFI settings.

2. Install VS Code & WSL Extension

  1. Download and install Visual Studio Code for Windows.
  2. Launch VS Code, open the Extensions view (Ctrl+Shift+X), and install the WSL extension (ms-vscode-remote.remote-wsl).

3. Connect VS Code to WSL

To ensure all coding and terminal commands run inside Ubuntu rather than Windows:

  1. Click the remote indicator button in the bottom-left corner of VS Code (the >< icon), or press Ctrl+Shift+P.
  2. Select WSL: New WSL Window.
  3. A new window will open. Confirm that the bottom-left indicator now displays WSL: Ubuntu.

Always verify that your VS Code window displays WSL: Ubuntu in the bottom-left corner. All subsequent steps and course exercises must be run within this connected WSL environment.

4. Update Ubuntu Packages & Install uv

Open the integrated terminal in your WSL-connected VS Code (View > Terminal or Ctrl+`).

  1. Update packages:

    sudo apt update && sudo apt upgrade -y

  2. Install uv:

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

  3. Reload your shell configuration:

    source ~/.bashrc

  4. Verify the installation:

    uv --version

5. Import the GECS Profile

  1. In VS Code, click the Manage gear icon in the lower-left corner and select Profiles > Import Profile….

  2. Paste the following URL and click Create:

    https://gist.github.com/igorsdub/04f6a1191dde8e09091a1099fe87d5be

  3. Accept any suggested extension installations.

If profile import fails, open Extensions (Ctrl+Shift+X) in your WSL window and install: - Python (Microsoft) - Data Science Extension Pack (Microsoft) - Ruff (Astral Software)

6. Git Identity Configuration

In the VS Code WSL terminal, configure Git. If you enabled email privacy in Step 1, use your GitHub-generated no-reply email address:

git config --global user.name "Your Name"
# Use your institutional email, or your private GitHub no-reply address:
git config --global user.email "your.email@oist.jp"
git config --global init.defaultBranch main

If you enabled Keep my email addresses private on GitHub, replace "your.email@oist.jp" with your private address (e.g. "12345678+username@users.noreply.github.com").

Troubleshooting

If you encounter difficulties during installation:

  • Setup Clinic: Join the informal pre-course setup clinic to troubleshoot environment issues with instructors.
  • BIOS Virtualization on Windows: If WSL reports that virtualization is disabled, enter your PC BIOS/UEFI settings on startup and enable Intel VT-x or AMD-V depending on your CPU.
  • macOS PATH issues: If running code in the terminal returns command not found, open VS Code, press Cmd+Shift+P, run Shell Command: Install 'code' command in PATH, and restart your terminal.
  • GitHub 2FA Backup: Always save your GitHub recovery codes in a secure location (such as a password manager) so you never lose access to your account.

References