Setting Up Python

Installing Python

Getting the right Python installation from the start saves a lot of confusion later. The key principle: always install the latest stable Python 3 release, and never rely on the version that came pre-installed with your operating system.

Windows

Download the installer from python.org/downloads. During installation, two checkboxes matter — missing either one means manually editing environment variables later:

• Check Add Python to PATH
• Check Install pip
• Use the default installation directory

Verify the install:

python --version   # Python 3.12.x
pip --version      # pip 24.x

macOS

macOS ships with an ancient Python 2.7 that exists only for legacy system scripts. You need to install the current Python 3 separately — the system Python should never be used for your projects. Install via Homebrew for the cleanest experience:

brew install python
python3 --version  # Python 3.12.x

Or use the official installer from python.org — both work fine.

Linux (Debian/Ubuntu)

Linux distributions often ship with a Python 3 version that lags behind the current release. Install the latest alongside the system Python — the python3-venv package is easy to miss but required for virtual environments.

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

Using pyenv (Recommended for Managing Multiple Versions)

pyenv is the cleanest solution when you maintain several projects pinned to different Python versions. It intercepts the python command at the shell level and redirects to whichever version you have configured for that directory — no manual PATH editing required.

# Install pyenv (macOS/Linux)
curl https://pyenv.run | bash

# Install and activate a specific version
pyenv install 3.12.3
pyenv global 3.12.3

# Per-project version — creates a .python-version file in the directory
cd my-project
pyenv local 3.11.9

Virtual Environments

A virtual environment is an isolated Python installation scoped to a single project. Without it, every pip install goes into a shared global location where packages from different projects can collide and break each other. With it, each project has its own clean, reproducible dependency set.

Creating and Activating

# Create a virtual environment named .venv in the current directory
python -m venv .venv

# Activate it
# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

# Your prompt changes to show the active environment:
# (.venv) $

Once activated, python and pip point to the virtual environment, not the system installation.

Deactivating

deactivate

The .gitignore Entry

The virtual environment directory contains compiled bytecode and machine-specific binaries — it should never go into version control. Your dependencies belong in requirements.txt or pyproject.toml, not the .venv folder itself.

# .gitignore
.venv/
__pycache__/
*.pyc
*.pyo
.env

Managing Packages with pip

pip is Python’s package installer. It downloads packages from PyPI (the Python Package Index), which hosts over 500,000 open-source libraries. Always run pip after activating your virtual environment so packages install into the project’s isolated environment, not globally.

# Install a package
pip install requests

# Install a specific version — pin versions in production to prevent surprise breakage
pip install "requests==2.31.0"

# Install from requirements file
pip install -r requirements.txt

# Freeze current dependencies — run this before sharing a project
pip freeze > requirements.txt

# Upgrade a package
pip install --upgrade requests

# Uninstall
pip uninstall requests

# List installed packages
pip list

requirements.txt vs pyproject.toml

For modern projects, prefer pyproject.toml (used by Poetry and PDM) over requirements.txt because it separates direct dependencies from transitive ones and supports version ranges with locking. For simple scripts and tutorials, requirements.txt is perfectly fine.

# pyproject.toml (Poetry example)
[tool.poetry.dependencies]
python = "^3.11"
requests = "^2.31"
fastapi = "^0.110"

Setting Up VS Code

VS Code is the most popular Python editor, with first-class support for virtual environments, debugging, and inline type checking. The extensions below transform it from a text editor into a full Python IDE.

1. VS Code
2. The Python extension by Microsoft
3. The Pylance extension for fast type checking

Selecting the Interpreter

After opening a project folder, press Ctrl+Shift+P → “Python: Select Interpreter” → choose the .venv interpreter. VS Code will use this interpreter for linting, autocomplete, and the integrated terminal — if you skip this step, you’ll get confusing “module not found” errors even when your packages are installed.

Recommended settings.json

These settings enable automatic formatting on save (using Black) and fast linting (using Ruff), which eliminates most style debates and catches common bugs as you type.

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter"
  },
  "python.linting.enabled": true,
  "python.linting.ruffEnabled": true
}

Useful Extensions

Running Your First Program

This example demonstrates three Python conventions you’ll see throughout real codebases: type hints, docstrings, and the __main__ guard.

def greet(name: str) -> str:
    """Return a greeting string for the given name."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    # input() reads a line from stdin and returns it as a string
    name = input("Enter your name: ")
    print(greet(name))

Run it:

(.venv) $ python hello.py
Enter your name: Alice
Hello, Alice!

Running the REPL

The Python REPL (Read-Eval-Print Loop) is an interactive shell that evaluates expressions immediately and prints the result. It’s the fastest way to test a snippet, explore an API, or check what a function returns without writing a full script.

python
>>> 2 + 2
4
>>> "hello".upper()
'HELLO'
>>> [x**2 for x in range(5)]
[0, 1, 4, 9, 16]
>>> exit()

For a better REPL experience, install IPython — it adds syntax highlighting, tab completion, magic commands, and persistent history:

pip install ipython
ipython

IPython’s magic commands like %timeit (benchmark an expression) and %run (execute a script) make it a powerful interactive development tool.

Common Setup Mistakes

Mistake 1: Using pip install without activating a venv Packages install globally and version conflicts pile up over time. Always activate first.

Mistake 2: Committing .venv/ to git The virtual environment is hundreds of MB and machine-specific. Use requirements.txt or pyproject.toml instead.

Mistake 3: Mixing Python 2 and Python 3 If python and python3 both exist on your system, always use python3 (or better, use pyenv to make one canonical).

Mistake 4: Forgetting to freeze dependencies Before sharing a project, run pip freeze > requirements.txt so others can reproduce your environment exactly.