Skip to main content

3  Setting Up Your Environment

3.1 Why This Matters

Every analysis in this course uses the same small stack: R, Positron, Quarto, and Git. Set it up carefully on Day 1 so later weeks begin from a working baseline rather than an unexpected debugging session.

This chapter walks through installation and configuration on both Mac and Windows. Follow every section in order. The verification steps may feel small, but they catch silent install failures while they are still easy to fix.

3.2 Learning Goals

By the end of this chapter, you should have:

  • R installed and running
  • Rtools installed (Windows only)
  • Positron open with R detected automatically
  • Fira Code or a Nerd Font rendering in the editor
  • air formatting a test file on save
  • A color theme that is comfortable for long sessions
  • Clean-slate reproducibility settings enabled
  • A GitHub account with Student Developer Pack activated
  • gh authenticated and able to clone a repository
  • First GitHub Classroom assignment accepted and cloned

3.3 Vocabulary

Term Meaning
IDE Integrated Development Environment — the app where you write and run code
Positron Posit’s modern IDE for R and Python, built on VS Code
air An R code formatter built into Positron; auto-fixes style on save
Homebrew Mac package manager — installs and updates command-line tools and apps with one command
Rtools Windows-only compiler toolchain required for building R packages from source
ligature font A programming font that merges multi-character symbols (e.g., |> renders as a single arrow glyph)
format on save Editor setting that runs air automatically every time you save a file
clean slate R session setting that prevents leftover objects from one session contaminating the next
gh GitHub’s official command-line tool — authenticate, clone repos, create issues, all from the terminal
PAT Personal Access Token — a credential that gives tools like gh permission to act on your GitHub account
GitHub Classroom GitHub service that creates a private copy of an assignment repository for each student
Student Developer Pack Free GitHub Pro tier for verified students — includes GitHub Copilot and other tools

3.4 Mac Prerequisites — Homebrew

NoteMac users: do this first

Windows users skip to Step 1.

Mac needs two things before anything else: the Xcode Command Line Tools (Apple’s compiler and Git) and Homebrew (the Mac package manager). Everything else installs in one command after that.

3.4.1 1. Xcode Command Line Tools

Open Terminal (Cmd+Space → type terminal → Enter) and run:

xcode-select --install

A dialog will appear asking to install developer tools. Click Install. This takes 5–10 minutes. When it finishes, verify:

git --version

Should print git version 2.x.x.

3.4.2 2. Homebrew

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

Follow the prompts. When it finishes, Apple Silicon Macs only — run the two lines it prints at the end to add Homebrew to your PATH. They look like:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
eval "$(/opt/homebrew/bin/brew shellenv)"

Intel Macs do not need this step.

Verify:

brew --version

3.4.3 3. Install course tools with one command

This installs Git, GitHub CLI, Quarto, Positron, GitHub Desktop, and the Fira Code Nerd Font in one step:

brew install git gh quarto && \
brew install --cask positron github font-fira-code-nerd-font

This takes a few minutes. When it finishes, skip ahead to Step 3 (Positron configuration). You can skip Steps 1–2 below — R is the only thing that still needs a manual installer.

WarningInstall R From CRAN, Not Homebrew

brew install r exists but should not be used for this course. The Homebrew version of R does not use the official macOS R framework, which causes problems with binary packages and Positron integration. Install R from CRAN as described in Step 1 below.

3.5 Step 1 — Install R

3.5.1 Mac

  1. Go to cran.r-project.org and click Download R for macOS.
  2. Check your chip:
    • Apple menu → About This Mac → look for “Apple M” (M1/M2/M3/M4) or “Intel”
    • Apple Silicon (M-series): download the arm64 .pkg
    • Intel: download the x86-64 .pkg
  3. Open the downloaded .pkg and follow the installer.

Verify: Open Terminal and run:

R --version

Should print something like R version 4.x.x.

3.5.2 Windows

  1. Go to cran.r-project.org → Download R for Windows → base.
  2. Download and run the installer. Accept all defaults.

Verify: Open Command Prompt and run:

R --version

3.6 Step 2 — Install Rtools (Windows Only)

Many R packages require compilation. Without Rtools, those installs will fail silently or with cryptic errors.

  1. Go to cran.r-project.org/bin/windows/Rtools.
  2. Download the Rtools version that matches your R version (e.g., Rtools44 for R 4.4.x).
  3. Run the installer. Accept all defaults — do not change the install path.

Verify: In R:

pkgbuild::has_build_tools(debug = TRUE)

Should print TRUE. If pkgbuild is not installed: install.packages("pkgbuild") first.

3.7 Step 3 — Install Positron

TipMac users who ran the Homebrew one-liner

Positron is already installed. Open it from Applications and skip to the verify step below.

Windows and Mac manual install:

  1. Go to positron.posit.co and download for your OS.
    • Mac M-series: choose the Apple Silicon build.
    • Mac Intel or Windows: choose the standard download.
  2. Run the installer.
  3. Open Positron. It will scan for R installations automatically.

Verify: Open the R console panel at the bottom of Positron and run:

R.version$version.string

Should print your R version. If Positron cannot find R, go to Settings (Cmd+, / Ctrl+,) → search r.path and point it at your R executable.

3.8 Step 4 — Install a Programming Font

Ligature fonts make R code easier to read by rendering multi-character operators as single glyphs. Both options below are free.

TipMac users who ran the Homebrew one-liner

Fira Code Nerd Font is already installed. Skip to Configure Positron to use the font below.

3.8.1 Option A — Mac (manual) or Windows: Fira Code

Mac (manual):

brew install --cask font-fira-code

Windows:

  1. Go to the Fira Code releases page.
  2. Download the latest .zip, extract it, open the ttf/ folder.
  3. Select all .ttf files → right-click → Install for all users.

3.8.3 Configure Positron to use the font

Open Settings (Cmd+, / Ctrl+,) and search font family. Set:

"editor.fontFamily": "FiraCode Nerd Font, Fira Code, Consolas, monospace",
"editor.fontLigatures": true,
"editor.fontSize": 14

Verify: Open any .R file. The |> pipe should render as a single arrow glyph (not two separate characters).

3.9 Step 5 — Configure air (Format on Save)

air is bundled with Positron. One setting enables it:

  1. Open Settings (Cmd+, / Ctrl+,).
  2. Search formatOnSave.
  3. Check Editor: Format On Save.

Verify:

  1. Create a new .R file.

  2. Type this badly spaced code:

    x<-c(1,2,3)
mean(x,na.rm=TRUE)

  3. Save the file (Cmd+S / Ctrl+S).

  4. Spacing should correct itself instantly:

    x <- c(1, 2, 3)
mean(x, na.rm = TRUE)

If air does not trigger, check View → Output → air for error messages.

3.10 Step 6 — Pick a Color Theme

A comfortable theme reduces eye strain during long coding sessions. All themes below are free.

3.10.1 Built-in themes (no install needed)

  • Dark+ — Positron default dark theme; high contrast, works everywhere
  • Light+ — High contrast light theme; good for projectors and bright rooms

3.11 Step 7 — Configure Clean-Slate Reproducibility

This is the most important setting in the entire guide. If skipped, your scripts may appear to work but fail when anyone else runs them.

Open Settings (Cmd+, / Ctrl+,) and add these to your settings.json (click the {} icon in the top-right of Settings):

{
  "r.session.restoreWorkspace": false,
  "r.session.saveWorkspace": "never"
}

What this does: R will never save or restore .RData files automatically. Every session starts empty. If your script breaks in a fresh session, that means it was relying on invisible state — which means it would break for anyone else who ran it.

Verify: Restart the R session (Cmd+Shift+F10 / Ctrl+Shift+F10). The Environment panel should show nothing. Type ls() in the console — should return character(0).

3.12 Step 8 — Enable the Native Pipe

R 4.1+ includes a built-in pipe operator |>. Enable the keyboard shortcut:

  • Open Settings → search native pipe → enable R: Use Native Pipe Operator.
  • Shortcut: Cmd+Shift+M (Mac) or Ctrl+Shift+M (Windows) inserts |>.

This course uses |> throughout. The older %>% pipe from magrittr works identically for our purposes; you may see it in older code online.

3.13 Step 9 — Create a GitHub Account

  1. Go to github.com and click Sign up.
  2. Use your UNL email address (yourname@huskers.unl.edu or yourname@unl.edu). This is required for the Student Developer Pack in Step 10.
  3. Choose a username carefully — it appears on every repository you create and will be visible to advisors and future employers. firstlast or first-last formats work well.
  4. Complete the account setup and verify your email address.

3.13.1 Enable Two-Factor Authentication

GitHub requires 2FA for all accounts. After signing in:

  1. Click your profile photo → Settings → Password and authentication.
  2. Under Two-factor authentication, click Enable.
  3. Use an authenticator app (Google Authenticator, Authy, or 1Password) — not SMS, which is less secure.
  4. Save your recovery codes somewhere safe (password manager or printed).

3.14 Step 10 — GitHub Student Developer Pack

The Student Developer Pack gives you free GitHub Pro, which includes GitHub Copilot and unlimited private repositories. Apply once; it lasts while you are enrolled.

3.14.1 Apply

  1. Go to education.github.com/pack and click Sign up for Student Developer Pack.
  2. Sign in with the GitHub account you just created.
  3. Select Student and enter your school name (University of Nebraska-Lincoln).
  4. Use your .unl.edu or .huskers.unl.edu email address for verification.

3.14.2 UNL-specific note

WarningUNL email addresses do not have an expiration date

GitHub’s automated verification looks for an expiration date in your school email or student ID. UNL email addresses do not encode one, so automated verification will likely fail.

Fix — upload proof of enrollment manually:

  1. When GitHub’s verification fails, look for the option to upload documentation.
  2. Log in to myred.unl.edu, navigate to Enrollment Verification, and download an enrollment letter or unofficial transcript.
  3. Upload that document to GitHub’s verification form.
  4. Approval usually takes 1–3 business days.

3.14.3 Verify

After approval, go to your GitHub profile → Settings → Billing and plans. You should see GitHub Pro listed under your current plan.

3.15 Step 11 — Install and Authenticate the GitHub CLI (gh)

The gh CLI lets you clone assignment repos, check Actions feedback, and interact with GitHub Issues all from the terminal — without a browser.

3.15.1 Install

TipMac users who ran the Homebrew one-liner

gh is already installed. Skip to Authenticate below.

Windows:

Open PowerShell and run:

winget install GitHub.cli

If winget is not available, download the installer from cli.github.com and run it.

Verify the install:

gh --version

3.15.2 Authenticate

Run this in Terminal (Mac) or PowerShell (Windows):

gh auth login

Answer the prompts:

Prompt Choose
Where do you use GitHub? GitHub.com
What is your preferred protocol? HTTPS
Authenticate Git with your GitHub credentials? Yes
How would you like to authenticate? Login with a web browser

A one-time code appears in the terminal. Press Enter — your browser opens. Paste the code and click Authorize github. Return to the terminal when it says “Authentication complete.”

3.15.3 Set your git identity

Git needs to know your name and email to label commits. Run these in the terminal (substitute your own details):

git config --global user.name "Your Name"
git config --global user.email "yourname@huskers.unl.edu"

Use the same email address as your GitHub account.

3.15.4 Verify everything with check_git_installation()

Run this in the Positron R console to check git, your identity, and your stored credentials all at once:

source("https://raw.githubusercontent.com/chrischizinski/class_helper/refs/heads/main/git_checkR.R")

This function (written by your instructor) will install the packages it needs automatically, then print a summary:

── Checking git installation ──────────────────────────────
✔ Git version 2.x.x installed on your system

── Checking your git configuration ────────────────────────
✔ You have your git user.name and user.email set up

── Checking your tokens ────────────────────────────────────
✔ Your tokens are setup

── Git check summary ───────────────────────────────────────
• Git installed:        ✔
• Username and email:   ✔
• Token:                ✔

All three should show ✔ before moving to Step 12. If any show ✖, follow the instructions printed in the output.

3.16 Step 12 — Accept a GitHub Classroom Assignment and Clone It

Every week, the instructor posts an assignment link. Here is what happens when you click it.

3.16.1 First time — authorize GitHub Classroom

The first assignment link asks you to authorize GitHub Classroom to create repositories on your behalf. Click Authorize GitHub Classroom. This is a one-time step.

3.16.2 Select your name from the roster

The instructor loads a class roster. When prompted, find your name in the list and click it. This links your GitHub account to the course gradebook. If your name is not there, skip for now and tell the instructor — do not guess.

3.16.3 Wait for repo creation

After accepting, GitHub creates a private repository named something like week-01-yourname. This takes about 30 seconds. Refresh the page and click the repo link when it appears.

3.16.4 Clone with gh

Copy the repository name from the page (format: org-name/repo-name), then run:

gh repo clone org-name/repo-name

This downloads the repo to your current directory and configures the remote automatically. Open the resulting folder in Positron:

cd repo-name

Then in Positron: File → Open Folder and select the cloned folder, or drag the folder into Positron.

NoteWhy not GitHub Desktop for cloning?

GitHub Desktop works too, and is fine for the first few weeks. The gh CLI becomes more useful as the course progresses — it lets you check CI feedback (gh run list), open Issues, and work entirely from the terminal. Both tools are installed; use whichever feels natural.

3.17 Book-Wide Output Habit

Every week, do one final check before you call the work done:

  1. Run it from a clean R session.
  2. Read the output as if you were not the person who wrote the code.
  3. Write one sentence that says what the output shows, what changed, or what decision it supports.
  4. Check the file path so the result is saved where the project expects it.

That habit matters more than making the code look clever. A script that runs but produces an unexplained table, plot, or report is not finished professional work.

3.18 Common Problems

brew: command not found after install (Apple Silicon)
The Homebrew PATH setup step was skipped. Run: 
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc && source ~/.zshrc
Then close and reopen Terminal.
Positron does not detect R
Go to Settings → search r.path → set the full path to your R executable. On Mac: /Library/Frameworks/R.framework/Versions/Current/Resources/bin/R. On Windows: C:\Program Files\R\R-4.x.x\bin\R.exe.
air does not format on save
Confirm Format On Save is checked. Check View → Output → air for errors. On Windows, confirm R is on the PATH.
Rtools not found after install (Windows)
Restart Positron after installing Rtools. If still failing, open R console and run Sys.getenv("PATH") — confirm the Rtools usr\bin path appears.
Font ligatures not rendering
Confirm "editor.fontLigatures": true is in settings.json. Confirm the font name exactly matches what was installed (check Font Book on Mac or Fonts in Control Panel on Windows).
Package installs fail with “no compiler” error (Mac)
Run xcode-select --install in Terminal. Restart Positron.
GitHub Student Developer Pack verification rejected
UNL email addresses have no expiration date, so automated verification fails. Upload an enrollment letter from myred.unl.edu manually when prompted. Approval takes 1–3 business days.
gh auth login opens browser but says “already authenticated” with wrong account
Run gh auth logout first, then gh auth login again.
gh repo clone fails with “repository not found”
Confirm you accepted the assignment (the link creates the repo — visiting the link without accepting does nothing). Verify gh auth status shows your account. Confirm the org and repo name are copied exactly.
Roster name not found in GitHub Classroom
If you are unsure which name to select, pause before choosing. Email the instructor with your GitHub username so they can add you manually; that is much easier than undoing the wrong account link later.
winget not found (Windows)
Update Windows to version 1809 or later, or download the gh installer directly from cli.github.com.

3.19 Try It

Run both checks below in the Positron R console. All items should pass before Module 01.

3.19.1 Check 1 — R packages

required_packages <- c("tidyverse", "here", "palmerpenguins", "quarto")

missing <- required_packages[
  !vapply(required_packages, requireNamespace, logical(1), quietly = TRUE)
]

if (length(missing) > 0) install.packages(missing)

message("R version: ", getRversion())
message("Working directory: ", getwd())
message("R setup complete.")

All four packages should install without errors. If any fail on Windows with a compilation error, revisit Step 2 (Rtools).

3.19.2 Check 2 — Git and GitHub credentials

source("https://raw.githubusercontent.com/chrischizinski/class_helper/refs/heads/main/git_checkR.R")

All three items in the summary (Git installed, Username and email, Token) should show ✔.

3.20 Connect to the Assignment

Module 01 starts from a working environment. Before accepting the first GitHub Classroom assignment:

  • R runs in Positron ✓
  • air formats on save ✓
  • Clean-slate settings enabled ✓
  • tidyverse, here, palmerpenguins installed ✓
  • GitHub account created and 2FA enabled ✓
  • Student Developer Pack applied (approval may still be pending — that is fine for Module 01) ✓
  • gh auth status shows your GitHub username ✓
  • Module 01 assignment accepted and cloned ✓

3.21 Finish the Professional Workflow

This course uses the same setup as working data scientists at research agencies and universities. The habits established here — reproducible sessions, automatic formatting, version-controlled projects — are not course requirements. They are professional standards that will follow you into your career.

When something breaks (and it will), the first question is always: does this work in a fresh R session? The clean-slate setting makes that question answerable in ten seconds instead of an hour.