Updated for Python 3.14 · November 2026

Install Python & Set Up
Your Dev Environment

A complete walkthrough for Windows, macOS, and Linux — installing Python 3, configuring VS Code, running your first scripts, and creating virtual environments. About 20 minutes from start to finish.

Start the setup Back to curriculum
terminal
$ python3 --version
Python 3.14.6

$ python3 hello.py
Hello, Python! 🐍

📋 What You'll Set Up

Everything you need to write, run, and debug Python code like a professional developer

🎯 Setup at a Glance

You don't need much to write Python. Technically, you could write Python in a text file and run it with a single command. But a proper development environment makes everything easier — autocomplete, error highlighting, debugging, and organized projects.

This guide walks you through each tool, explains why you need it (not just how to install it), and ends with a working "Hello, World" plus a small calculator that proves your setup works.

15–20 minutes Windows, macOS, Linux Beginner friendly
🐍

Python 3.14

The interpreter itself — the program that reads and runs your Python code. Any current stable Python 3 works.

Step 1
💻

VS Code

A free, powerful code editor with great Python support. Autocomplete, debugging, and an integrated terminal.

Step 2
🏃

First Scripts

Write and run a real Python program — Hello World, plus a small calculator.

Step 3
📦

Virtual Environments

An isolated package space per project, so one project's dependencies can't break another's.

Step 4

🧭 Your Setup Progress

Tick each step as you finish it. Your progress is saved in this browser only.

0 of 6 steps done

⬇️ Download Python 3

Get the latest stable Python 3 release for your operating system

Official source only

Always download Python from python.org. Never download Python from a third-party website — it may contain malware or a tampered interpreter.

🪟 Windows Installation

Python now ships for Windows through the Python install manager, which python.org recommends for most users. It installs and updates Python for you and gives you the py command.

Recommended
  1. Open the Microsoft Store and search for "Python Install Manager" (published by the Python Software Foundation). Or get it from https://www.python.org/downloads/.
  2. Click "Get" / "Install". Alternatively, in a terminal run: winget install 9NQ7512CXL7T
  3. Open a new PowerShell window and run py install. This downloads the latest stable Python.
  4. Accept any prompts from the first-run configuration check (it may offer to add shortcuts or fix aliases).
  5. Verify: run py --version. You should see a 3.14.x version.
💡 The install manager updates itself automatically, and py list --online shows every Python version you can install. It requires Windows 10 or newer.
⚠️ If you previously installed the old "Python launcher", uninstall it first — both use the py command and can conflict.

Alternative: the traditional installer (.exe)

Still available for now, but python.org has announced it will stop being released with Python 3.16. If you use it:

  1. Download and run the .exe from python.org/downloads.
  2. Check "Add python.exe to PATH" at the bottom of the first screen. This is the most commonly missed option.
  3. Click "Install Now", wait about 30 seconds, then click "Close".

🍎 macOS Installation

macOS may include a python3 that comes with Apple's developer tools. That's a system Python you should not modify. Install a fresh one for development.

  1. Open your browser and go to https://www.python.org/downloads/
  2. Click the yellow "Download Python 3.x.x" button. The installer is a .pkg file.
  3. Run the .pkg file and click "Continue" through the license agreement, then "Install".
  4. Authenticate with your password when prompted.
  5. Click "Close". Python is installed under /Library/Frameworks/Python.framework/ and linked into /usr/local/bin.
  6. Open a new Terminal and run python3 --version to confirm.
💡 Prefer Homebrew? Install it from brew.sh, then run brew install python. Updates become a single brew upgrade python.
💡 Don't delete or install packages into the system Python. Use a virtual environment for every project (covered below).

🐧 Linux Installation

Most Linux distributions already ship with Python 3. First check what you have — then install the extras (pip and venv) if needed.

# Check what version you have:
python3 --version

# Ubuntu / Debian:
sudo apt update
sudo apt install python3 python3-pip python3-venv

# Fedora / RHEL:
sudo dnf install python3 python3-pip

# Arch Linux:
sudo pacman -S python python-pip

# Verify after install:
python3 --version
python3 -m pip --version
💡 On Debian and Ubuntu, venv and pip are separate packages, so install python3-venv and python3-pip alongside Python itself.

Which Python version should I choose?

Choose the latest stable Python 3 — currently the 3.14 series. Avoid Python 2 entirely (discontinued in 2020). If your Linux distro only offers 3.11 or 3.12, that's fine — everything in this curriculum works with 3.11+.

⚙️ After Installing

A few quick post-install steps make sure everything runs smoothly

✅ Post-Install Checklist

After running the installer on any platform, complete these steps:

  • ✓Open a new terminal window (terminals opened before installing don't see the change).
  • ✓Confirm Python is on your PATH — see the next section.
  • ✓Update pip to the latest version: python3 -m pip install --upgrade pip (use py on Windows). Skip this step if you get an "externally-managed-environment" error — see Troubleshooting.
  • ✓Create a workspace folder, for example ~/projects/python.

✅ Confirm Python Works

Check the version, try the interactive shell, and create your workspace

🧪 Check the Version

Open a terminal (Terminal on macOS/Linux, PowerShell on Windows) and run:

# macOS / Linux:
python3 --version

# Windows:
py --version

# Also check pip (use "py -m pip" on Windows):
python3 -m pip --version
💡 You should see something like Python 3.14.6. Your patch number may differ — that's fine. If you see command not found or is not recognized, jump to Troubleshooting.

🔀 Which Command Do I Type?

The command names differ between operating systems. This table is the cheat sheet used throughout this guide.

Python commands by operating system
TaskWindowsmacOS / Linux
Check versionpy --versionpython3 --version
Run a scriptpy hello.pypython3 hello.py
Install a packagepy -m pip install requestspython3 -m pip install requests
Create a venvpy -m venv .venvpython3 -m venv .venv
Activate the venv.venv\Scripts\Activate.ps1source .venv/bin/activate
Leave the venvdeactivatedeactivate
💡 Once a virtual environment is active, plain python and pip work on every OS and always point at the environment's own Python.

🐚 Try the Python REPL

The REPL (Read-Eval-Print Loop) is an interactive shell where you type Python code and see results immediately. It's the fastest way to test ideas.

$ python3
Python 3.14.6 (main, ...) [...] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> print("Hello, Python!")
Hello, Python!
>>> 2 + 2
4
>>> exit()
$
💡 Type exit() or press Ctrl+D (macOS/Linux) or Ctrl+Z then Enter (Windows) to leave the REPL.

📁 Create Your Workspace

A dedicated folder keeps your Python projects organized. We'll use it for the rest of this guide.

# Windows PowerShell:
mkdir $HOME\projects\python
cd $HOME\projects\python

# macOS / Linux:
mkdir -p ~/projects/python
cd ~/projects/python

# Confirm the current directory:
pwd
💡 If you close the terminal, reopen it and cd back into this folder before continuing.

💻 Install VS Code & the Python Extension

Your code editor — where you'll write every Python script from now on

Python code can be written in any text editor, including Notepad. But a modern editor like VS Code dramatically improves the experience: it highlights errors before you run the code, autocompletes names, shows inline documentation, and lets you debug with breakpoints — all from one window.

📥 Step 1 — Download VS Code

  1. Go to https://code.visualstudio.com in your browser.
  2. Click the download button for your operating system.
  3. Run the installer. The default options are fine. On Windows, the optional "Add to PATH" and "Open with Code" items are handy.
  4. Launch VS Code after the install finishes.

🐍 Step 2 — Install the Python Extension

The Python extension turns VS Code from a general text editor into a Python IDE. It adds syntax highlighting, code completion, linting, debugging, and notebook support.

  1. Open the Extensions view from the left sidebar, or press Ctrl+Shift+X (Cmd+Shift+X on macOS).
  2. Search for "Python". Pick the one published by Microsoft.
  3. Click "Install".
  4. Check that "Pylance" was installed with it — it's the language server behind the smart autocomplete. It normally comes bundled automatically.
💡 Always check the publisher name. Lookalike extensions exist, and only Microsoft's official Python extension is maintained alongside Pylance.

🗂️ Step 3 — Open Your Project Folder

VS Code works best when you open a folder as a workspace. This enables "run this file", debugging, and per-project settings.

  1. Click File → Open Folder (or press Ctrl+K then Ctrl+O).
  2. Select your workspace folder — the projects/python folder you created earlier.
  3. Click "Open", and choose "Yes, I trust the authors" if VS Code asks about workspace trust (it's your own folder).

⚙️ Step 4 — Select the Python Interpreter

If you have multiple Python installations, VS Code needs to know which one to use.

  1. Press Ctrl+Shift+P (Cmd+Shift+P on macOS) to open the Command Palette.
  2. Type "Python: Select Interpreter" and press Enter.
  3. Choose the interpreter with the highest version number, for example Python 3.14.x.
💡 The selected interpreter is shown in the bottom-right status bar when a .py file is open. After you create a .venv (below), VS Code usually offers to switch to it automatically — say yes.

🏃 Write & Run Your First Scripts

Now that Python and VS Code are set up, let's write real programs

📝 Step 1 — Create a New File

  1. In VS Code, click File → New Text File.
  2. Save it immediately with Ctrl+S (Cmd+S on macOS).
  3. Name it hello.py. The .py extension tells VS Code and Python what kind of file this is.
  4. Save it in your projects/python folder.

✍️ Step 2 — Write the Code

Type the following into hello.py. You can also press Run below to try it right here in your browser — a small dialog will ask for your name.

def greet(name: str) -> str:
    return f"Hello, {name}! Welcome to Python 🐍"

if __name__ == "__main__":
    user = input("What is your name? ")
    print(greet(user))
💡 The 4-space indentation is not cosmetic — Python uses indentation to define code blocks. VS Code inserts spaces for Python files by default.

▶️ Step 3 — Run It

There are three ways to run a script, and each is useful in different situations:

  1. Open the integrated terminal with Ctrl+` (backtick).
  2. Type python3 hello.py (py hello.py on Windows) and press Enter.
  3. Type your name when prompted and press Enter.
  4. You should see: Hello, [your name]! Welcome to Python 🐍
  1. Open Terminal (macOS/Linux) or PowerShell (Windows).
  2. Move into your folder: cd ~/projects/python (Windows: cd $HOME\projects\python)
  3. Run: python3 hello.py (py hello.py on Windows)
  4. Type your name at the prompt and press Enter.
  1. With hello.py open, look at the top-right corner of VS Code.
  2. Click the ▶️ play button — VS Code runs the file in a terminal for you.
  3. Type your name at the prompt.
💡 The play button is the quickest way to test a script, but if your script reads files from a specific folder, run it from the terminal inside that folder instead.

🎉 What You Just Did

You wrote and ran a real Python program that:

  • ✓Defined a function (def greet(...)) with a type hint and return annotation
  • ✓Used an f-string to embed a variable in a string (f"Hello, {name}!")
  • ✓Used the if __name__ == "__main__": guard, so the main body only runs when the file is executed directly — not when imported
  • ✓Read user input with input() and displayed output with print()

Every one of these concepts is explained in the Python Basics lesson. For now, what matters is that your environment works.

🧮 Bonus — A Small Calculator

One more script to prove your setup handles real logic. Save it as calc.py, run it, then try changing it — add a new operation, or handle invalid numbers differently.

def calculate(a: float, op: str, b: float) -> float:
    if op == "+":
        return a + b
    if op == "-":
        return a - b
    if op == "*":
        return a * b
    if op == "/":
        if b == 0:
            raise ZeroDivisionError("Cannot divide by zero")
        return a / b
    raise ValueError(f"Unknown operator: {op}")

if __name__ == "__main__":
    try:
        a = float(input("First number: "))
        op = input("Operator (+ - * /): ").strip()
        b = float(input("Second number: "))
        print(f"{a} {op} {b} = {calculate(a, op, b)}")
    except (ValueError, ZeroDivisionError) as err:
        print(f"Error: {err}")
💡 Notice how the program handles bad input gracefully with try / except instead of crashing. You'll learn this in the Exception Handling lesson.

📦 Virtual Environments

The single most important habit in professional Python development

Before you install a single third-party package, understand virtual environments. Skip this and you'll eventually hit problems: two projects needing different versions of the same library, or a system Python broken by a bad install. Use them and you'll avoid all of that.

🤔 Why Virtual Environments Matter

Imagine you're working on two projects:

  • ✓Project A needs one version of a library (say, requests 2.31)
  • ✓Project B needs a different, older version of the same library

If you install packages globally, both projects share one environment and you can only have one version installed at a time. A virtual environment gives each project its own isolated set of packages, so they never interfere.

🚀 Creating Your First Virtual Environment

Python ships with the venv module — nothing extra to install on Windows and macOS (Debian/Ubuntu need python3-venv). Create it once per project, activate it whenever you work on that project.

# Move into your project folder:
cd ~/projects/python

# Create a virtual environment named ".venv":
python3 -m venv .venv          # Windows: py -m venv .venv

# Activate it — macOS / Linux:
source .venv/bin/activate

# Activate it — Windows PowerShell:
.venv\Scripts\Activate.ps1

# Activate it — Windows Command Prompt:
.venv\Scripts\activate.bat

# Your prompt now starts with (.venv). Plain "python" works everywhere:
python --version
💡 Name it .venv. Every tool in the Python ecosystem expects that: VS Code detects it automatically and standard .gitignore templates already exclude it.
⚠️ PowerShell says "running scripts is disabled"? Run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once, then activate again.

📥 Installing Packages Inside a Virtual Environment

While the environment is active, pip installs packages into it instead of globally.

# Inside your activated virtualenv:
python -m pip install requests

# See what's installed:
python -m pip list

# Save your dependencies to a file:
python -m pip freeze > requirements.txt

# Recreate them elsewhere:
python -m pip install -r requirements.txt
💡 Commit requirements.txt to Git but never commit the .venv folder. Add .venv/ to .gitignore — it can be hundreds of megabytes and is trivial to recreate.

🚪 Deactivating a Virtual Environment

When you're done, leave the environment with one command.

(.venv) $ deactivate
$ python3 --version

# Deactivating doesn't delete anything. Reactivate any time.
💡 Deactivating only tells your shell to stop using the environment. The .venv folder stays, ready to activate again.

🔗 The One-Command Shortcut

Every new project starts the same way: make a folder, create an environment, activate it. Here's a one-liner for each platform:

# macOS / Linux:
mkdir my_project && cd my_project && python3 -m venv .venv && source .venv/bin/activate

# Windows PowerShell:
mkdir my_project; cd my_project; py -m venv .venv; .venv\Scripts\Activate.ps1
💡 Bookmark this snippet — you'll use it dozens of times over the course of the curriculum.

Curious about modern tooling?

Tools like uv and poetry automate environments and dependency management. Learn plain venv and pip first — they're what everything else builds on. The Virtual Environments in Depth lesson covers the rest.

➡️ What's Next

Your environment is ready — here's where to go from here

🏁

Start Python Basics

Beginner

Variables, data types, print(), input(), comments — your first real programming concepts.

Start lesson
📐

Python Syntax & Indentation

Beginner

The rules that make Python code readable — and the ones that break your code if you ignore them.

Start lesson
📦

Python Variables

Beginner

How Python stores and retrieves values, and why assignment works the way it does.

Start lesson
🧰

Virtual Environments in Depth

Intermediate

pip, poetry, uv, requirements.txt, and the modern package management workflow.

Start lesson

🔧 Troubleshooting Common Problems

The most frequent issues — with clear fixes

By far the most common issue. Your shell can't find the command, usually because Python isn't on your PATH or you're using the wrong command name.

On Windows: Try py --version first — if you installed with the Python install manager, py is the command to use. If you used the traditional installer and skipped the "Add python.exe to PATH" box, re-run the installer, choose "Modify", and enable "Add Python to environment variables". Then open a new terminal.

On macOS/Linux: Use python3 instead of python. Most systems don't create a plain python command outside a virtual environment.

Windows ships "app execution aliases" that redirect python to the Store when Python isn't found. Fix it by installing Python (see above), then open Settings → Apps → Advanced app settings → App execution aliases and turn off the python.exe and python3.exe aliases that point to the Store installer. Open a new terminal and try py --version.

pip is included with Python, but the bare pip command isn't always on your PATH. Use the module form, which always works:

# macOS / Linux:
python3 -m pip --version

# Windows:
py -m pip --version

If even that fails on Debian/Ubuntu, install pip with sudo apt install python3-pip.

Modern Linux distributions and Homebrew mark their Python as "externally managed" (PEP 668) to stop pip from breaking system tools. This is a protection, not a bug. The fix is a virtual environment: create one as described in Virtual Environments, activate it, then run pip install as usual.

Don't use --break-system-packages unless you fully understand the risk.

You have several Pythons installed and your shell picks a different one than you expect. Diagnose with:

# macOS / Linux:
which -a python3

# Windows PowerShell:
py list
Get-Command python

The first match on your PATH wins. The cleanest fix is to always work inside a virtual environment — the active environment's Python takes precedence automatically.

pip is trying to write to a system-wide location you don't own. Fix: create and activate a virtual environment (see above). Inside it you have full write access.

Avoid sudo pip install — it can corrupt system packages. If you truly need a global install, pip install --user package installs into your home directory instead.

If VS Code shows "No interpreter selected" even though Python works in the terminal, try these in order:

  1. Run "Python: Select Interpreter" from the Command Palette and pick the right version.
  2. If the list is empty, choose "Enter interpreter path…" and browse to your Python executable.
  3. Restart VS Code so it picks up the newly installed Python.
  4. On macOS/Linux, if you launched VS Code from the Dock, it may use a different PATH than your terminal. Try launching it from a terminal with code .

With the python.org installer, run the certificate script that ships with Python so HTTPS downloads work:

# Adjust the version number to match yours:
open "/Applications/Python 3.14/Install Certificates.command"

You can also double-click Install Certificates.command in Finder, inside the Python 3.x folder in Applications.

Uninstall Python the same way you'd remove any application — via the OS or package manager, not by deleting files by hand.

Windows: Settings → Apps → Installed apps → find "Python Install Manager" or "Python 3.x" → Uninstall. With the install manager, py uninstall removes individual runtimes and py uninstall --purge does a full cleanup.

macOS: Remove the framework version you installed (for example /Library/Frameworks/Python.framework/Versions/3.14) and the matching links in /usr/local/bin. Never touch /usr/bin/python3 — that belongs to the system.

Linux: Use your package manager, e.g. sudo apt remove python3.x. Never remove the system Python package — many system tools depend on it.

Still stuck?

Ask in the Python Discord's help channels. Include your operating system, the Python version, and the exact error message — copy it as text rather than a screenshot.

❓ Frequently Asked Questions

Common questions about Python installation and setup

Python 3 — always. Python 2 reached end-of-life on January 1, 2020 and no longer receives security updates. Every library, tool, and tutorial you're likely to meet targets Python 3. If a tutorial uses Python 2, it's out of date.

No. Python runs well on modest hardware. Most memory and CPU use comes from the libraries you install — heavy machine-learning libraries can be demanding, but you don't need them for the basics. This curriculum's browser-based code runner is even lighter: it runs entirely in your browser via WebAssembly.

Yes! Every runnable example on this site executes in your browser using Pyodide, a version of Python compiled to WebAssembly. Click "Run" on any Python snippet. You can complete the first several lessons without installing anything. Still, installing Python locally is worth doing eventually — it lets you work on real projects, install packages, and use professional tools.

VS Code is the most popular choice and what this guide recommends — it's free, cross-platform, and the Python extension is excellent. Other good options: PyCharm (more powerful, heavier, with a free Community edition), Sublime Text (fast and light, more manual setup), or Jupyter (best for data science and interactive exploration). Pick one and stick with it while you learn.

A little. Four commands cover most of what you need at first: cd (change directory), ls / dir (list files), pwd (where am I), and mkdir (make a folder). A few hours of practice with the terminal pays for itself many times over as your projects grow.

For most learners, plain Python from python.org is the right choice. Anaconda bundles Python with hundreds of data-science packages, which is convenient if you're immediately doing heavy data work but adds complexity (and several gigabytes) while you're learning the language. You can always install pandas and NumPy individually later.

No — install Python once per machine and reuse it. What you create per project is a virtual environment: a lightweight, isolated space for that project's packages. Creating one takes a couple of seconds. See Virtual Environments.

Chromebook: Linux support in ChromeOS gives you a real terminal where you can install Python normally.

iPad: Apps such as Pythonista (paid) or Carnets provide a Python environment on the iPad.

Android: Pydroid 3 is a complete Python IDE with pip support.

On any device, you can also use this site's browser-based runner — no install needed.

A new minor version arrives roughly once a year, in October. Python 3.13 came out in October 2024 and 3.14 in October 2025. Each version gets about five years of support, with bug-fix releases on a regular schedule. You don't need to upgrade immediately — staying within a version or two of the latest is fine, and differences are small for most beginner code. Check python.org for the newest release.

Yes, and it's common — many developers keep two or three for testing. Virtual environments keep projects from interfering with each other. On Windows, the Python install manager handles several versions side by side (py -3.13 script.py picks a specific one). On macOS and Linux, a version manager such as pyenv or uv gives you fine-grained control.

🗒️ Your Notes

Jot down questions, commands that worked, or reminders for yourself. Notes are saved in this browser only — they aren't published or shared.

No notes yet — add your first one above.