Installing Python & VS Code Setup: Windows, macOS, and Linux

Learn how to install Python, configure environment variables, set up VS Code, manage packages with pip, and isolate dependencies using virtual environments.

Table of Contents

  1. Introduction
  2. Learning Objectives
  3. Prerequisites
  4. Installing Python on Windows
  5. Installing Python on macOS
  6. Installing Python on Linux
  7. The PATH Environment Variable Explained
  8. Managing Packages with pip
  9. Isolating Dependencies: Virtual Environments (venv)
  10. Setting Up Visual Studio Code for Python
  11. Visual Environment Flow
  12. Troubleshooting Common Installation Issues
  13. Best Practices for Environment Management
  14. Security Notes
  15. Interview Insights
  16. Frequently Asked Questions (FAQs)
  17. Summary
  18. Related Tutorials

Introduction

Before you can write Python code to build web servers, train machine learning models, or automate daily tasks, you need to set up your development environment.

A professional development environment requires more than just installing Python. You must understand how to configure system paths, manage external packages using pip, isolate dependencies using virtual environments (venv), and configure a code editor like Visual Studio Code with linters and debuggers. This guide provides a step-by-step setup guide for Windows, macOS, and Linux.

Learning Objectives

By the end of this tutorial, you will be able to:

  • Install Python 3 on Windows, macOS, and Linux.
  • Configure environment variables and system PATH settings.
  • Verify installation endpoints using Command Prompt or Terminal.
  • Manage external libraries using the pip package manager.
  • Create, activate, and manage isolated virtual environments.
  • Configure VS Code with the Microsoft Python extension, formatter, and linter.

Prerequisites

Installing Python on Windows

Step 1: Download the Installer

Go to the official downloads page at python.org/downloads/windows and download the latest stable release of the Python 3 Windows installer (64-bit).

Step 2: Run the Installer (Crucial Step)

Double-click the downloaded .exe file to start the installer.

> [!IMPORTANT] > Check the PATH Box: At the bottom of the installer window, you MUST check the box labeled "Add python.exe to PATH". If you skip this, your command line will not recognize Python commands, requiring manual configuration of environment variables later.

Step 3: Complete Installation

Select "Install Now" to complete the installation. At the end of the installation process, if prompted, select "Disable path length limit" to allow Python to handle long file paths.

Step 4: Verify Installation

Open Command Prompt (cmd) and run:

python --version

If configured correctly, the command returns your installed version (e.g. Python 3.12.3).

To check if the package manager was installed successfully, run:

pip --version

Installing Python on macOS

macOS comes with a default Python implementation, but it is typically an outdated system version (often Python 2.x or a customized version of Python 3) used for system processes. Do not modify or use the system Python for your projects. Instead, install a separate, clean release.

Method A: Using Homebrew (Recommended)

Homebrew is a popular package manager for macOS that simplifies installing development tools.

  1. Open Terminal.
  2. Install Homebrew (if not already installed) by running the official setup command from brew.sh.
  3. Run the following command to install the latest Python release: 
    brew install python
  4. Verify the installation: 
    python3 --version
pip3 --version

Method B: Using python.org Installer

If you do not use Homebrew, you can install Python using the official macOS installer:

  1. Go to python.org/downloads/macos and download the macOS installer package (.pkg file).
  2. Run the installer and follow the on-screen prompts.

Installing Python on Linux

Most Linux distributions (like Ubuntu, Debian, Fedora, Arch) come with Python pre-installed. However, you may need to install the package manager (pip) and virtual environment libraries manually.

On Ubuntu / Debian-based Distributions:

Open your terminal and run:

sudo apt update
sudo apt install python3 python3-pip python3-venv -y

On Fedora / Red Hat-based Distributions:

sudo dnf install python3 python3-pip python3-virtualenv -y

On Arch Linux:

sudo pacman -S python python-pip

Verify your installation:

python3 --version
pip3 --version

The PATH Environment Variable Explained

When you type a command (like python or git) into your command line, the operating system does not search your entire computer for that program. Instead, it looks in a list of directory paths stored in a system variable called PATH.

If you forget to check the "Add to PATH" box during the Windows installation, typing python returns an error: 'python' is not recognized as an internal or external command.

How to Manually Add Python to Windows PATH:

  1. Search for "Environment Variables" in the Windows Start Menu and select "Edit the system environment variables".
  2. Select "Environment Variables..." at the bottom of the System Properties window.
  3. Under User Variables, select the Path variable and click "Edit...".
  4. Click "New" and add the paths to your Python installation folder and Scripts folder. These folders are typically located at:
    • C:\Users\<Username>\AppData\Local\Programs\Python\Python312\
    • C:\Users\<Username>\AppData\Local\Programs\Python\Python312\Scripts\
  5. Click OK to save the changes, restart your Command Prompt, and verify your setup.

Managing Packages with pip

pip (Pip Installs Packages) is the official package manager for Python. It allows you to download and manage third-party libraries from the Python Package Index (PyPI).

Common pip Commands:

  1. Installing a Package: 
    pip install requests
  2. Upgrading an Installed Package: 
    pip install --upgrade requests
  3. Uninstalling a Package: 
    pip uninstall requests
  4. Listing Installed Packages: 
    pip list
  5. Exporting Dependency Lists: Export your project's dependencies to a requirements.txt file so other developers can install them easily: 
    pip freeze > requirements.txt
  6. Installing from a Dependency List: To install all packages listed in a requirements.txt file, run: 
    pip install -r requirements.txt

Isolating Dependencies: Virtual Environments (venv)

By default, when you install packages using pip install, they are installed globally on your computer.

If Project A requires Django 3.2 and Project B requires Django 5.0, installing one globally will overwrite the other, breaking your projects. To prevent this, always use a Virtual Environment (venv) to isolate dependencies for each project.

Global System
  ├── Project A Environment (venv) ──> Django 3.2
  └── Project B Environment (venv) ──> Django 5.0

Step-by-Step Virtual Environment Setup:

1. Create the Environment

Navigate to your project directory in the terminal and run:

# On Windows
python -m venv myenv

# On macOS / Linux
python3 -m venv myenv

This creates a folder named myenv in your project directory containing a copy of the Python interpreter and pip.

2. Activate the Environment

You must activate the virtual environment before installing packages:

# On Windows (Command Prompt)
myenv\Scripts\activate.bat

# On Windows (PowerShell)
myenv\Scripts\Activate.ps1

# On macOS / Linux
source myenv/bin/activate

Once activated, your terminal prompt will show the environment name in parentheses, e.g. (myenv) user@computer:~$.

3. Deactivate the Environment

To exit the virtual environment and return to global settings, run:

deactivate

Setting Up Visual Studio Code for Python

Visual Studio Code (VS Code) is a popular code editor for Python development.

Step 1: Download VS Code

Download and install the editor for your operating system from the official page at code.visualstudio.com.

Step 2: Install Python Extension

  1. Open VS Code.
  2. Click on the Extensions icon on the left sidebar (or press Ctrl+Shift+X / Cmd+Shift+X).
  3. Search for "Python" and install the extension published by Microsoft.

Step 3: Select Your Python Interpreter

To ensure VS Code uses your virtual environment:

  1. Open your project folder in VS Code.
  2. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
  3. Type "Python: Select Interpreter" and select it.
  4. Select the Python interpreter path inside your virtual environment (e.g. ./myenv/bin/python or .\myenv\Scripts\python.exe).

Step 4: Configure Linters and Formatters

For clean code formatting, we configure VS Code to use Black (a popular code formatter) and Ruff (a fast linter):

  1. Install formatters in your virtual environment: 
    pip install black ruff
  2. Open your VS Code settings.json file and add the following settings to format your code automatically on save: 
    {
  "editor.formatOnSave": true,
  "python.formatting.provider": "black",
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.codeActionsOnSave": {
      "source.organizeImports": "explicit"
    }
  }
}

Visual Environment Flow

graph LR
    OS[Install Python 3 on OS] --> PATH[Configure PATH variables]
    PATH --> ProjectDir[Create Project Directory]
    ProjectDir --> Venv[Create virtual env: python -m venv myenv]
    Venv --> Active[Activate myenv]
    Active --> Pip[Install packages: pip install -r requirements.txt]
    Pip --> IDE[Open folder in VS Code & Select myenv Interpreter]

Troubleshooting Common Installation Issues

1. "Python is not recognized as an internal or external command"

  • Cause: The installer did not add the Python execution folder to your system PATH variable.
  • Solution: Re-run the installer and check the "Add to PATH" box, or add the paths manually in your system environment settings.

2. "pip: command not found"

  • Cause: The package manager was not installed, or PATH settings are missing.
  • Solution: On Windows, re-run the installer and select "Modify" to verify pip is selected. On Linux, run sudo apt install python3-pip to install it.

3. Execution Policy Errors in PowerShell

  • Cause: Windows blocks running scripts (like activate.ps1) by default for security.
  • Solution: Open PowerShell as Administrator and run the following command to allow script execution: 
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Best Practices for Environment Management

  • Never Commit Virtual Environments to Git: A virtual environment folder (like myenv) contains thousands of binary files specific to your operating system. Never commit it to GitHub. Instead, add the folder name to your .gitignore file and document your dependencies in a requirements.txt file.
  • Isolate Every Project: Never install third-party libraries globally. Always create a virtual environment for each project to prevent dependency version conflicts.

Security Notes

  • Beware of Package Squatting: When installing packages using pip install <name>, double-check the spelling of the package name. Attackers sometimes publish malicious packages with names similar to popular libraries (like typing reqeusts instead of requests) to inject malicious code into your development environment.
  • Keep pip Updated: Keep your package manager updated to ensure you have the latest security patches: 
    python -m pip install --upgrade pip

Interview Insights

Typical Interview Questions:

  1. Why do we use virtual environments in Python? Answer Key: Virtual environments isolate dependencies for each project, preventing conflicts between different versions of libraries installed globally.
  2. What does the PATH environment variable do? Answer Key: The PATH variable is a list of directory paths where the operating system searches for executable programs when you run commands in the terminal.
  3. How do you share project dependencies with other developers? Answer Key: Export your dependencies to a requirements.txt file using pip freeze > requirements.txt. Other developers can install them in their environment by running pip install -r requirements.txt.

Frequently Asked Questions (FAQs)

Q: Do I need a separate virtual environment for every project? A: Yes. It is best practice to create a separate virtual environment for each project to keep dependencies clean and prevent version conflicts.

Q: Can I run multiple Python versions on the same computer? A: Yes. You can install multiple Python versions (like 3.10 and 3.12) on your computer. In your terminal, call the specific version (e.g. python3.10 or python3.12) to run code on that version, or manage installations using tools like pyenv.

Summary

Setting up a Python development environment requires installing Python 3, configuring system PATH settings, using pip to manage third-party libraries, and isolating dependencies for each project using virtual environments. Configuring VS Code with formatters like Black helps you write standard code.

Related Tutorials

← Back to Syllabus