What this page does
Introduces what you will learn in this guide.
Where this fits
This is the starting point. Assumes you completed Project Setup.
Explanation
By the end of this guide, you will know how to:
- Install VS Code — Download and set up on Mac
- Navigate the Interface — Understand every panel and view
- Work with Files — Create, open, save, and organize
- Use the Terminal — Run Python directly in VS Code
- Install Extensions — Add Python support and more
- Use Shortcuts — Work faster with keyboard commands
- Customize Settings — Make VS Code your own
Why this matters
VS Code is the most popular code editor. Learning it well makes you more productive.
⚠ If something breaks here
Nothing to break yet. Move to Page 2.
What this page does
Downloads VS Code to your Mac.
Where this fits
First step: get the installer.
Code (this page)
Open browser
Go to: https://code.visualstudio.com
Click: Download for Mac
Explanation
- Open Safari or Chrome
- Go to
code.visualstudio.com
- The site detects you're on Mac
- Click the big blue "Download" button
A
.zip file downloads to your Downloads folder.
Why this matters
VS Code is free and actively maintained by Microsoft. It's the industry standard.
⚠ If something breaks here
- Site not loading: Check internet connection
- Wrong version: Make sure it says "Mac" on the download button
What this page does
Installs VS Code on your Mac.
Where this fits
File downloaded. Now install it.
Code (this page)
1. Open Downloads folder
- Double-click the .zip file
- Drag "Visual Studio Code" to Applications
Explanation
- Open Finder → Downloads
- Find the VS Code
.zip file
- Double-click to extract (creates "Visual Studio Code.app")
- Drag the app to your Applications folder
This makes VS Code available system-wide.
Why this matters
Proper installation in Applications ensures VS Code updates correctly and integrates with macOS.
⚠ If something breaks here
- Can't open .zip: Right-click → Open With → Archive Utility
- "App is damaged": System Settings → Privacy & Security → Open Anyway
What this page does
Opens VS Code for the first time.
Where this fits
VS Code is installed. Now launch it.
Code (this page)
Press: Command + Space
Type: Visual Studio Code
Press: Enter
Explanation
Use Spotlight (Command + Space) to quickly launch apps.
Alternatively:
- Open Finder → Applications → Visual Studio Code
First launch may ask for permissions. Click "Allow" or "Open."
Why this matters
You'll launch VS Code daily. Spotlight is the fastest method.
⚠ If something breaks here
- "Cannot be opened": Go to System Settings → Privacy & Security → Open Anyway
- Slow to open: First launch is slow, subsequent launches are faster
What this page does
Explains what you see when VS Code first opens.
Where this fits
VS Code is open. Understand the welcome view.
Explanation
The Welcome tab shows:
- Start — New File, Open Folder, Clone Repository
- Recent — Recently opened folders and files
- Learn — Links to documentation and tutorials
- Customize — Theme and settings quick links
You can close this tab. It reappears each launch unless disabled.
Why this matters
The Welcome screen provides quick access to common actions. Useful for beginners.
⚠ If something breaks here
- No Welcome tab: Click Help → Welcome in the menu bar
- Different layout: You may have opened it before, that's fine
What this page does
Maps out the main areas of VS Code.
Where this fits
You see VS Code. Now understand its layout.
Explanation
VS Code has five main areas:
┌─────────────────────────────────────────┐
│ Menu Bar │
├─────┬───────────────────────────────────┤
│ │ │
│ A │ Editor │
│ c │ Area │
│ t │ │
│ i │ │
│ v ├───────────────────────────────────┤
│ i │ Panel │
│ t │ (Terminal, Output) │
│ y │ │
├─────┴───────────────────────────────────┤
│ Status Bar │
└─────────────────────────────────────────┘
- Activity Bar — Left icons (Files, Search, Extensions)
- Sidebar — File explorer, search results, etc.
- Editor Area — Where you write code
- Panel — Terminal, Problems, Output
- Status Bar — Bottom info bar
Why this matters
Knowing the layout helps you find features and navigate efficiently.
⚠ If something breaks here
Nothing to break. This is orientation.
What this page does
Explains the Sidebar and how to toggle it.
Where this fits
You know the layout. Now explore the Sidebar.
Code (this page)
Toggle Sidebar: Command + B
Explanation
The Sidebar shows contextual content based on which Activity Bar icon is selected:
| Icon | View |
| 📄 | Explorer — Files and folders |
| 🔍 | Search — Find across files |
| 🔀 | Source Control — Git integration |
| 🐛 | Run and Debug — Debugging tools |
| 🧩 | Extensions — Install add-ons |
Press Command + B to hide or show the Sidebar.
Why this matters
The Sidebar is your navigation hub. Learn to toggle it for more editor space.
⚠ If something breaks here
- Sidebar won't toggle: Click View → Appearance → Show Primary Sidebar
What this page does
Explains where you write and edit code.
Where this fits
You know the Sidebar. Now focus on the Editor.
Explanation
The Editor Area is the main workspace. Features:
- Tabs — Open files appear as tabs at the top
- Line numbers — Left column shows line numbers
- Minimap — Right side shows code overview (optional)
- Cursor — Blinking line where you type
Multiple files can be open in tabs. Click a tab to switch.
Why this matters
You'll spend 90% of your time in the Editor Area.
⚠ If something breaks here
- No line numbers: View → Appearance → Show Line Numbers
- No minimap: That's fine, it's optional
What this page does
Explains the information shown in the Status Bar.
Where this fits
You know the Editor. Now understand the bottom bar.
Explanation
The Status Bar (bottom of window) shows:
| Position | Information |
| Left | Git branch, sync status |
| Center | Errors and warnings count |
| Right | Line/column, encoding, language |
Click items for quick actions:
- Click "Python" to change language mode
- Click "Ln/Col" to jump to a line
Why this matters
The Status Bar gives quick info without leaving your code.
⚠ If something breaks here
- No Status Bar: View → Appearance → Show Status Bar
What this page does
Shows how to open a project folder in VS Code.
Where this fits
You know the interface. Now open a real project.
Code (this page)
Press: Command + O (that's the letter O)
Or: File → Open Folder
Explanation
VS Code works best when you open a folder, not individual files.
- Press
Command + O or click File → Open Folder
- Navigate to your
projects folder (from Project Setup guide)
- Select
my-first-project (or any folder)
- Click "Open"
The folder appears in the Explorer sidebar.
Why this matters
Opening a folder gives VS Code context. It enables features like search, Git, and file navigation.
⚠ If something breaks here
- Empty sidebar: Make sure you opened a folder, not a file
- Wrong folder: File → Open Folder and try again
What this page does
Creates a new file inside your project.
Where this fits
Folder is open. Now create a file.
Code (this page)
Press: Command + N (new file)
Then: Command + S (save)
Name it: hello.py
Explanation
- Press
Command + N to create a new untitled file
- Type some code:
print("Hello, VS Code!")
- Press
Command + S to save
- Name it
hello.py and save in your project folder
The file appears in the Explorer sidebar.
Why this matters
Creating files is fundamental. The .py extension tells VS Code it's Python.
⚠ If something breaks here
- Can't save: Make sure you have write permission to the folder
- Wrong location: Check the save dialog shows your project folder
What this page does
Explains save options and indicators.
Where this fits
You created a file. Understand saving.
Code (this page)
Save: Command + S
Save All: Command + Option + S
Explanation
Unsaved indicator: A white dot appears on the tab when a file has unsaved changes.
Save options:
Command + S — Save current fileCommand + Option + S — Save all open files
Auto Save: VS Code can save automatically (covered in Settings later).
Why this matters
Losing work is frustrating. Know how to save and recognize unsaved files.
⚠ If something breaks here
- Dot doesn't appear: Make a change to the file, then check the tab
What this page does
Shows how to navigate files in the Explorer.
Where this fits
Files created. Navigate between them efficiently.
Code (this page)
Open Explorer: Command + Shift + E
Open file: Click it, or press Enter when selected
Explanation
In the Explorer sidebar:
- Single-click — Preview file (italicized tab, replaced by next preview)
- Double-click — Open file permanently (normal tab)
- Arrow keys — Navigate up/down through files
- Enter — Open selected file
Right-click a file for options: Rename, Delete, Copy Path, etc.
Why this matters
Fast navigation between files keeps you in flow.
⚠ If something breaks here
- Explorer not visible: Click the top icon in the Activity Bar (or
Command + Shift + E)
What this page does
Verifies you can navigate VS Code.
Where this fits
You have learned the interface basics.
Explanation
You should now be able to:
| Task | Method |
| Toggle Sidebar | Command + B |
| Open folder | Command + O |
| New file | Command + N |
| Save file | Command + S |
| Open Explorer | Command + Shift + E |
Why this matters
Navigation is the foundation. These shortcuts become muscle memory.
⚠ If something breaks here
Review pages 7-13 for any action you're unsure about.
What this page does
Introduces the most powerful feature in VS Code.
Where this fits
You know basic navigation. Now discover the Command Palette.
Code (this page)
Open Command Palette: Command + Shift + P
Explanation
Press Command + Shift + P to open the Command Palette.
This is a search box for every VS Code command:
- Type to search
- Use arrow keys to select
- Press Enter to run
Try it: Type "toggle sidebar" and press Enter.
The Command Palette replaces memorizing dozens of menus.
Why this matters
If you forget a shortcut, the Command Palette finds it. It's your universal search.
⚠ If something breaks here
- Nothing happens: Make sure you press Command + Shift + P (not just Command + P)
- Command not found: Check spelling
What this page does
Opens the built-in Terminal in VS Code.
Where this fits
You know the Command Palette. Now access the Terminal.
Code (this page)
Open Terminal: Control + Backtick (the key below Escape)
Or: View → Terminal
Explanation
Press Control + Backtick to toggle the Terminal panel.
The Terminal opens at the bottom. It's the same as Mac Terminal but inside VS Code.
Your current directory is automatically set to your open folder.
Why this matters
Running Python without leaving VS Code keeps you focused.
⚠ If something breaks here
- Wrong key: The backtick is below Escape, left of the 1 key
- Terminal in wrong folder: Close and reopen VS Code with your folder
What this page does
Runs your Python file from the integrated Terminal.
Where this fits
Terminal is open. Now run Python.
Code (this page)
Explanation
Make sure you have hello.py open with:
print("Hello, VS Code!")
In the Terminal, type:
python3 hello.py
Press Enter. You should see:
Hello, VS Code!
Why this matters
This is the core workflow: write code in the Editor, run it in the Terminal.
⚠ If something breaks here
No such file: Make sure you're in the folder containing hello.pycommand not found: Python not installed, complete Project Setup guide
What this page does
Shows how to install VS Code extensions.
Where this fits
Basic VS Code works. Now enhance it.
Code (this page)
Open Extensions: Command + Shift + X
Explanation
Extensions add features to VS Code.
- Press
Command + Shift + X to open Extensions view
- The sidebar shows search box and installed extensions
- Search for extensions by name
- Click "Install" to add them
Extensions are free and managed by the community and Microsoft.
Why this matters
Extensions transform VS Code from a text editor into a full development environment.
⚠ If something breaks here
- Extensions not loading: Check internet connection
- Sidebar not changing: Click the Extensions icon (4 squares) in Activity Bar
What this page does
Installs the essential Python extension.
Where this fits
You can install extensions. Now install the most important one.
Code (this page)
1. Open Extensions (Command + Shift + X)
- Search: Python
- Find "Python" by Microsoft
- Click Install
Explanation
The Python extension by Microsoft adds:
- Syntax highlighting for
.py files
- IntelliSense (autocomplete)
- Linting (error detection)
- Debugging support
- Jupyter notebook support
Look for the extension with "Microsoft" as the publisher and millions of downloads.
Why this matters
Without this extension, VS Code doesn't understand Python. With it, VS Code becomes a Python IDE.
⚠ If something breaks here
- Multiple results: Choose the one by "Microsoft" with the most downloads
- Install fails: Check internet connection, try again
What this page does
Verifies you understand extensions.
Where this fits
You installed the Python extension.
Explanation
You should now be able to:
| Task | Method |
| Open Extensions | Command + Shift + X |
| Search extensions | Type in search box |
| Install | Click Install button |
| Manage | Click gear icon on installed extensions |
Recommended extensions for Python:
- Python (Microsoft) ✅ Installed
- Pylance (Microsoft) — Enhanced IntelliSense
- Python Debugger (Microsoft) — Debugging
The Python extension often installs Pylance automatically.
Why this matters
Extensions make VS Code powerful. Start with essentials, add more as needed.
⚠ If something breaks here
Review pages 18-19 if extensions aren't working.
What this page does
Shows how VS Code colors your code for readability.
Where this fits
Python extension installed. Now see it in action.
Explanation
Open hello.py or create a new Python file with:
def greet(name):
message = f"Hello, {name}!"
print(message)greet("World")
Notice the colors:
- Purple/Blue — Keywords (
def, print)
- Yellow — Function names
- Green — Strings
- White — Variables
Colors vary by theme but always distinguish code elements.
Why this matters
Syntax highlighting makes code readable. Errors become obvious when colors are wrong.
⚠ If something breaks here
- No colors: Make sure file is saved as
.py (check Status Bar shows "Python")
- Wrong colors: The Python extension may still be loading, wait a moment
What this page does
Demonstrates VS Code's intelligent code completion.
Where this fits
Syntax highlighting works. Now experience autocomplete.
Code (this page)
Explanation
Type import os and press Enter.
Then type os. (with the dot).
A popup appears showing all available methods:
os.pathos.getcwdos.listdir- ...and more
Use arrow keys to browse, Enter to select, Escape to dismiss.
Start typing to filter: os.getc shows only methods starting with "getc".
Why this matters
IntelliSense saves typing and prevents typos. You don't need to memorize every method.
⚠ If something breaks here
- No popup: Press
Control + Space to manually trigger
- Limited options: Python extension may still be indexing, wait a moment
What this page does
Shows how VS Code highlights errors in your code.
Where this fits
Autocomplete works. Now see error detection.
Code (this page)
Explanation
Type pritn("Hello") (intentional typo).
A red squiggly line appears under pritn. This indicates an error.
Hover your mouse over the squiggle to see the error message:
Fix it to
print and the squiggle disappears.
Yellow squiggles indicate warnings (not errors, but worth checking).
Why this matters
Catching errors while typing saves debugging time later.
⚠ If something breaks here
- No squiggles: The linter may be disabled. Install Pylance extension.
- Takes time: Error checking runs after a short delay
What this page does
Shows how to choose which Python VS Code uses.
Where this fits
Error detection works. Now configure the Python version.
Code (this page)
Command + Shift + P
Type: Python: Select Interpreter
Press Enter
Explanation
VS Code needs to know which Python to use.
- Open Command Palette (
Command + Shift + P)
- Type "Python: Select Interpreter"
- Press Enter
- Choose from the list:
- Global Python (
/opt/homebrew/bin/python3)
- Virtual environment (
./venv/bin/python)
If you're in a project with a venv, select the venv Python.
The selected interpreter shows in the Status Bar.
Why this matters
Selecting the right interpreter ensures VS Code uses the correct Python and packages.
⚠ If something breaks here
- No interpreters listed: Python not installed, complete Project Setup guide
- venv not listed: Make sure the venv exists in your open folder
What this page does
Shows multiple ways to run Python files.
Where this fits
Interpreter selected. Now run code.
Code (this page)
Method 1: Terminal
python3 filename.pyMethod 2: Right-click
Right-click in editor → Run Python File in Terminal
Method 3: Play button
Click ▶ in top-right corner
Explanation
Three ways to run:
- Terminal — Type
python3 filename.py (you know this)
- Right-click — Right-click in the editor, select "Run Python File in Terminal"
- Play button — Click the ▶ triangle in the top-right of the editor
All three open the Terminal and run your file.
Why this matters
Multiple options let you choose what's fastest for your workflow.
⚠ If something breaks here
- No Play button: Python extension not installed or file isn't
.py
- Wrong Python: Check the interpreter (Page 24)
What this page does
Explains the Run button in detail.
Where this fits
You know it exists. Now understand its options.
Explanation
The Run button (▶) in the top-right has a dropdown arrow.
Click the arrow to see options:
- Run Python File — Runs the entire file
- Run Python File in Dedicated Terminal — New terminal for this file
- Debug Python File — Run with debugger attached
For now, use "Run Python File" for quick execution.
Why this matters
Different run modes serve different purposes. Know what's available.
⚠ If something breaks here
- No dropdown: Click the small arrow next to the play button, not the button itself
What this page does
Verifies you can write and run Python in VS Code.
Where this fits
You have completed the Python features section.
Explanation
You should now be able to:
| Task | Method |
| See syntax colors | Automatic for .py files |
| Get autocomplete | Type and see suggestions, or Control + Space |
| See errors | Red squiggles appear automatically |
| Select interpreter | Command Palette → Python: Select Interpreter |
| Run Python | Terminal, right-click, or Play button |
Why this matters
These features make VS Code a complete Python development environment.
⚠ If something breaks here
Review pages 21-26. Most issues are solved by ensuring the Python extension is installed.
What this page does
Shows how to work with multiple files.
Where this fits
You can run Python. Now manage multiple files.
Code (this page)
New tab: Command + N
Switch tabs: Command + Option + Left/Right
Close tab: Command + W
Explanation
Open multiple files — each gets a tab.
Navigation:
- Click tabs to switch
Command + Option + Left/Right to move between tabsCommand + W to close current tabCommand + Shift + T to reopen last closed tab
Tabs can be dragged to reorder.
Why this matters
Real projects have many files. Efficient tab management keeps you productive.
⚠ If something breaks here
- Only one tab: Open more files from Explorer (double-click)
What this page does
Shows how to view multiple files side by side.
Where this fits
You have multiple tabs. Now view them simultaneously.
Code (this page)
Split right: Command + Backslash
Or: Drag a tab to the side of the editor
Explanation
To split the editor:
- Open two files in tabs
- Press Command + Backslash to split right
- Or drag a tab to the right edge until you see a highlight
- Drop to create a split view
Now you can see two files at once. Great for:
- Comparing files
- Referencing one file while editing another
- Viewing code and output
Why this matters
Side-by-side editing is essential for real development work.
⚠ If something breaks here
- Split doesn't work: Make sure you have at least one file open
- To unsplit: Close files in one pane or drag tabs back together
What this page does
Reinforces the most important shortcut.
Where this fits
Beginning the shortcuts section.
Code (this page)
Save: Command + S
Save All: Command + Option + S
Save As: Command + Shift + S
Explanation
You already know Command + S. Use it constantly.
Additional save commands:
Command + Option + S — Save all open files at onceCommand + Shift + S — Save current file with a new name/location
Pro tip: Save after every meaningful change. It becomes automatic.
Why this matters
Saving frequently prevents lost work. Make it a reflex.
⚠ If something breaks here
Nothing to break. Practice these shortcuts.
What this page does
Teaches find and replace shortcuts.
Where this fits
You can save. Now learn to find.
Code (this page)
Find in file: Command + F
Find and replace: Command + Option + F
Find in all files: Command + Shift + F
Explanation
Find in current file: Command + F
- Type search term
- Enter to find next
- Shift + Enter to find previous
- Escape to close
Find and replace: Command + Option + F
- Adds a "Replace" field
- Replace one or replace all
Find in all files: Command + Shift + F
- Searches entire project
- Results show in sidebar
Why this matters
Finding code quickly is essential as projects grow.
⚠ If something breaks here
- Search not working: Make sure the search box is focused (cursor blinking)
What this page does
Shows how to quickly comment/uncomment code.
Where this fits
You can find code. Now comment it.
Code (this page)
Toggle comment: Command + /
Block comment: Command + Option + /
Explanation
Place your cursor on a line and press Command + /.
The line becomes a comment:
# print("Hello")
Press again to uncomment.
Multiple lines: Select several lines, then Command + / to comment all.
Block comment: Command + Option + / creates multi-line comment syntax (if language supports it).
Why this matters
Quickly commenting code is essential for testing and debugging.
⚠ If something breaks here
- Wrong comment style: VS Code uses the correct style for each language
What this page does
Shows how to duplicate lines instantly.
Where this fits
You can comment. Now duplicate.
Code (this page)
Duplicate line: Command + Shift + D
Move line up: Option + Up
Move line down: Option + Down
Explanation
Place cursor on any line:
Command + Shift + D — Copies the line below itselfOption + Up — Moves the entire line upOption + Down — Moves the entire line down
Works with multiple selected lines too.
Why this matters
These shortcuts are faster than copy/paste for quick edits.
⚠ If something breaks here
- Nothing happens: Make sure cursor is on a line (not in a selection)
What this page does
Introduces VS Code settings.
Where this fits
You know shortcuts. Now customize VS Code.
Code (this page)
Open Settings: Command + ,
Explanation
Press Command + , to open Settings.
Two views:
- UI — Searchable graphical interface (default)
- JSON — Raw configuration file (click
{} icon)
Search for any setting by name. Changes save automatically.
Settings have two scopes:
- User — Apply to all projects
- Workspace — Apply to current project only
Why this matters
Settings let you customize VS Code to your preferences.
⚠ If something breaks here
- Settings not opening: Try Code → Settings → Settings from menu bar
What this page does
Shows how to change the color theme.
Where this fits
You can access Settings. Now change appearance.
Code (this page)
Command + K, then Command + T
Or: Settings → search "theme"
Explanation
Press Command + K, release, then press Command + T.
A list of themes appears:
- Use arrow keys to preview
- Enter to select
Popular themes:
- Dark+ (default dark) — VS Code default
- Light+ (default light) — Light version
- One Dark Pro — Popular community theme
- Dracula — Another popular dark theme
Install more themes from Extensions.
Why this matters
A comfortable theme reduces eye strain during long coding sessions.
⚠ If something breaks here
- Keyboard shortcut not working: Use Command Palette → "Preferences: Color Theme"
What this page does
Shows how to adjust editor font size.
Where this fits
Theme selected. Now adjust readability.
Code (this page)
Zoom in: Command + =
Zoom out: Command + -
Reset zoom: Command + 0Or: Settings → search "font size"
Explanation
Quick zoom:
Command + = makes everything largerCommand + - makes everything smallerCommand + 0 resets to default
For permanent change:
- Open Settings (
Command + ,)
- Search "font size"
- Change "Editor: Font Size" (default is 12)
14-16 is comfortable for most people.
Why this matters
Readable code reduces mistakes and eye strain.
⚠ If something breaks here
- Zoom affects everything: That's expected, it's a global zoom
- Font size setting: Only affects the editor, not the whole interface
What this page does
Enables automatic file saving.
Where this fits
Font configured. Now automate saving.
Code (this page)
Settings → search "auto save"
Change: Files: Auto Save
Options: off, afterDelay, onFocusChange, onWindowChange
Explanation
- Open Settings (
Command + ,)
- Search "auto save"
- Find "Files: Auto Save"
- Choose an option:
-
off — Manual save only (default)
-
afterDelay — Saves after you stop typing (1 second default)
-
onFocusChange — Saves when you click away from the file
-
onWindowChange — Saves when you switch applications
Recommended: afterDelay or onFocusChange
Why this matters
Auto save eliminates "forgot to save" errors.
⚠ If something breaks here
- Can't find setting: Search exactly "files auto save"
- Not saving: Check the delay time in "Files: Auto Save Delay"
What this page does
Verifies you can customize VS Code.
Where this fits
You have completed the settings section.
Explanation
You should now be able to:
| Task | Method |
| Open Settings | Command + , |
| Change theme | Command + K, Command + T |
| Zoom | Command + =/-/0 |
| Change font size | Settings → "font size" |
| Enable auto save | Settings → "auto save" |
Why this matters
A customized editor is more comfortable and productive.
⚠ If something breaks here
Review pages 34-37 for any setting you couldn't find.