Installation & Virtual Environments

Before Bookshelf gets a single route, it needs somewhere clean to live — an isolated Python environment where Flask and every package we add later belong only to this project. This lesson sets that up from scratch: creating the environment, activating it, installing Flask, and recording what got installed so the setup can be reproduced anywhere.

Why Virtual Environments Matter

A virtual environment is a private, self-contained copy of Python and its installed packages, kept separate from your system-wide Python and from every other project on your machine. Skip this step and every Python project you have shares one global pool of installed packages — which is fine right up until two projects need different versions of the same library.

Creating the Environment

Python has shipped the venv module in its standard library since Python 3.3, so nothing extra needs installing first. From inside the Bookshelf project folder, run:

python -m venv bookshelf-env

This creates a new folder named bookshelf-env holding a private copy of the Python interpreter and an empty space for packages, entirely separate from your system Python. The name is arbitrary — env or venv both work just as well — but naming it after the project makes its purpose obvious to anyone who opens the folder later.

Activating the Environment

Creating the environment doesn't start using it — you have to activate it, which points your current terminal session at that environment's Python and packages instead of the system-wide ones. The exact command depends on your operating system and shell:

Once activation succeeds, your terminal prompt typically changes to show the environment's name in parentheses, something like (bookshelf-env) C:\projects\bookshelf>, confirming you're inside the isolated environment rather than the system Python.

Installing Flask

With the environment active, install Flask using pip, Python's built-in package manager:

pip install flask

Because the virtual environment is active, Flask is installed only inside bookshelf-env — your system Python and any other project's environment stay completely untouched.

Verifying the Install

To confirm Flask installed correctly and see which version you have, run:

flask --version

This prints the installed Flask version along with the Python version it's running on. If the command isn't found at all, double-check that bookshelf-env is actually activated — that's the most common cause of this error.

Freezing Dependencies to requirements.txt

As Bookshelf grows and picks up more packages — Flask-SQLAlchemy, Flask-Login, Flask-WTF, and others in later lessons — it becomes important to record exactly which versions are installed, so the environment can be recreated identically elsewhere: on a teammate's machine, a CI server, or a production host.

pip freeze > requirements.txt

This writes every installed package and its exact version into a plain text file named requirements.txt. Anyone who clones the Bookshelf project afterward can recreate the same environment in one step:

pip install -r requirements.txt

This file becomes essential once we reach Configuration & Environments and, much later, Deployment — a production server needs to install the exact same dependency versions Bookshelf was built and tested against, and requirements.txt is what makes that possible.

Alternatives: pipenv and poetry

Plain venv plus pip freeze is the simplest setup available, and it's what this track uses throughout. Some teams prefer tools that combine environment management and dependency locking into a single workflow:

• pipenv — manages a virtual environment and a Pipfile together, automatically locking exact versions into a Pipfile.lock
• poetry — handles dependencies and packaging together through a pyproject.toml file, and is a common choice for projects that will eventually be published as installable packages

Either is a perfectly reasonable choice for a real team project. This track sticks with plain venv and requirements.txt because they need no extra installation and keep the focus on Flask itself rather than tooling choices.