Python Environment & Package Management

Every real Python project eventually needs code that someone else has already written — libraries like requests, pandas, or flask. This file covers how to install, organize, and manage these external packages properly, project by project.

1. What is pip?

What is it?

pip is Python's package manager — a command-line tool used to install, update, and remove third-party libraries (packages) that aren't part of Python's built-in Standard Library.

Definition: pip is the standard package installer for Python, used to download and manage libraries from the Python Package Index (PyPI).

Why do we use it?

Instead of writing everything yourself, pip lets you install ready-made, tested libraries with a single command — like requests for making web requests, or pandas for data analysis.

Basic pip Commands

bash
pip install requests              # install a package
pip install requests==2.28.0      # install a specific version
pip uninstall requests             # remove a package
pip list                           # list all installed packages
pip show requests                  # show details about a specific package
pip install --upgrade requests     # upgrade to the latest version
pip --version                      # check pip's version

Explanation

• pip install requests downloads the requests library from PyPI (the Python Package Index — an online repository of packages) and makes it available to import in your code.
• Pinning a specific version (==2.28.0) ensures consistent behavior — useful when a newer version might change something your code depends on.

Common Mistakes

• Forgetting to install a package before importing it, causing ModuleNotFoundError.
• Installing packages globally for every project, instead of per-project (this is exactly the problem virtual environments solve — see below).
• Using pip instead of pip3 (or vice versa) when both Python 2 and 3 are installed on older systems.

Important Points

• pip comes pre-installed with modern Python (3.4+).
• PyPI (pypi.org) is the central place packages are published to and installed from.

2. What is a Virtual Environment?

What is it?

A virtual environment is an isolated, self-contained Python setup for a specific project — with its own installed packages, completely separate from your system's global Python installation and other projects.

Definition: A virtual environment is an isolated Python environment that allows project-specific dependencies without affecting the global Python installation.

Why do we use it?

Imagine Project A needs django==3.0 and Project B needs django==4.2. If you installed packages globally, you could only have one version at a time — installing one would break the other project. Virtual environments solve this by giving each project its own isolated set of installed packages.

How does it work?

Python's built-in venv module creates a separate folder containing its own Python interpreter and package storage, isolated from the rest of your system.

Creating and Using a Virtual Environment

bash
# Create a virtual environment named "venv" in the current folder
python -m venv venv

# Activate it:
# On Windows:
venv\Scripts\activate

# On macOS/Linux:
source venv/bin/activate

# Your terminal prompt now shows (venv) - confirming it's active

# Install packages - these install ONLY inside this environment
pip install requests

# Deactivate when done
deactivate

Explanation of the Code

• python -m venv venv creates a new folder called venv containing an isolated Python setup.
• Activating it changes your terminal session so that python and pip commands use this isolated environment instead of your global Python installation.
• Any package installed while activated stays inside this environment — it won't affect other projects or your system-wide Python.

Real-World Example

Professional developers create a new virtual environment for every single project, ensuring each project's dependencies stay clean, isolated, and reproducible on any machine.

Common Mistakes

• Forgetting to activate the virtual environment before installing packages, accidentally installing them globally instead.
• Committing the entire venv folder to version control (like Git) — it should always be excluded (via .gitignore), since it can be recreated from requirements.txt on any machine.
• Forgetting to deactivate one environment before activating another.

Important Points

• Always create a fresh virtual environment for each new project.
• Add venv/ (or whatever you name the folder) to your .gitignore file.
• (venv) shown in your terminal prompt confirms the environment is currently active.

Practice

1. Create a new virtual environment, activate it, install the requests package, and confirm it's installed using pip list.

3. requirements.txt

What is it?

A simple text file listing every package (and often, version) your project depends on — used to recreate the exact same environment on another machine, or after cloning the project from Git.

Creating a requirements.txt File

bash
pip freeze > requirements.txt

This captures every currently installed package (and its exact version) in the active virtual environment, and writes them into requirements.txt.

Example requirements.txt Content

requests==2.31.0
flask==3.0.0
pandas==2.1.4

Installing From requirements.txt

bash
pip install -r requirements.txt

Explanation: This reads the file and installs every listed package at its specified version — exactly recreating the intended environment, whether on a teammate's laptop or a production server.

Real-World Example

When you clone almost any real Python project from GitHub, one of the very first setup steps is always: create a virtual environment, then run pip install -r requirements.txt.

Common Mistakes

• Forgetting to regenerate requirements.txt after installing new packages, so teammates end up with an outdated dependency list.
• Manually typing package names into requirements.txt instead of using pip freeze, risking typos or missed dependencies.

Important Points

• requirements.txt is the standard way to share exact project dependencies.
• Always regenerate it (pip freeze > requirements.txt) after adding or updating packages.

4. pyproject.toml (Modern Approach)

What is it?

pyproject.toml is a newer, more standardized configuration file for Python projects — used by modern tools (like Poetry, or newer pip versions) to define dependencies, build settings, and project metadata all in one place.

Example pyproject.toml

toml
[project]
name = "my-python-app"
version = "1.0.0"
description = "A sample Python application"
dependencies = [
    "requests>=2.31.0",
    "flask>=3.0.0"
]

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

Comparison Table — requirements.txt vs pyproject.toml

Important Points

• Both approaches are valid — requirements.txt remains extremely common and is perfectly fine for most learning projects and many production ones.
• pyproject.toml is becoming the modern standard, especially for packages meant to be published or larger, more structured applications.

5. Python Version Management

What is it?

Different projects sometimes need different Python versions (not just different packages) — for example, one older project might require Python 3.9, while a newer one uses Python 3.12. Tools like pyenv (on macOS/Linux) let you install and switch between multiple Python versions easily.

Basic Concept (No Deep Dive Needed at This Stage)

bash
pyenv install 3.11.0     # install a specific Python version
pyenv local 3.11.0        # use that version for the current project folder

Important Points

• Virtual environments (venv) manage packages per project; version managers like pyenv manage the Python interpreter version itself.
• For most beginner and intermediate projects, a single up-to-date Python 3 version combined with venv is more than sufficient — version management tools become more relevant working across multiple legacy projects professionally.

Common Beginner Mistakes — Summary for This Section

• Installing packages globally instead of inside a project-specific virtual environment.
• Forgetting to activate the virtual environment before installing packages.
• Committing the venv folder to Git instead of just requirements.txt.
• Forgetting to update requirements.txt after installing new packages.

Cheat Sheet — Environment & Package Management

bash
# pip
pip install package_name
pip install package_name==1.2.3
pip uninstall package_name
pip list
pip show package_name
pip install --upgrade package_name

# virtual environments
python -m venv venv
venv\Scripts\activate          # Windows
source venv/bin/activate       # macOS/Linux
deactivate

# requirements.txt
pip freeze > requirements.txt
pip install -r requirements.txt

Interview Questions

Q1. What is `pip`? Answer: Python's standard package manager, used to install, update, and remove third-party libraries from PyPI (the Python Package Index).

Q2. Why are virtual environments important? Answer: They isolate a project's dependencies from the global Python installation and from other projects, preventing version conflicts between projects that need different versions of the same package.

Q3. What is `requirements.txt` used for? Answer: It lists all the packages (and typically their exact versions) a project depends on, allowing the same environment to be recreated on another machine using pip install -r requirements.txt.

Q4. What command creates a virtual environment? Answer: python -m venv venv (where venv is the chosen folder name for the environment).

Q5. What's the difference between `requirements.txt` and `pyproject.toml`? Answer: requirements.txt is a simple list of dependencies. pyproject.toml is a more modern, structured configuration file that can include dependencies alongside project metadata and build settings.

Practice Questions

Beginner

1. Create a virtual environment and activate it on your operating system.
2. Install the requests package inside your activated virtual environment.
3. List all currently installed packages using pip list.
4. Generate a requirements.txt file from your current environment.
5. Deactivate your virtual environment.

Intermediate

1. Create a new virtual environment, install two packages of your choice, and generate a requirements.txt from it.
2. Delete your virtual environment folder, recreate a new one, and reinstall everything using pip install -r requirements.txt.
3. Explain (in your own words, in comments) why committing a venv folder to Git is considered bad practice.

Challenge

1. Set up a small project with a pyproject.toml file listing two dependencies, and explain what each section of the file does.
2. Simulate a version-conflict scenario in writing: describe how two different projects needing different versions of the same package would cause problems without virtual environments, and how venv solves it.