Install Flask and Create a Route

You've written Python scripts that crunch numbers or process files, but when you try to turn that logic into something a user can actually click, type into, or see in a browser, the walls go up. Maybe you've copy-pasted a "Hello World" Flask snippet from a blog post, only to stare at an empty terminal or a ModuleNotFoundError. The pain is real: the gap between knowing Python and shipping a web app feels enormous — but it doesn't have to be. By the end of this lesson, you'll have Flask installed, a running dev server, and your very first route responding to HTTP requests — the foundation for every API and web app you'll build from here on out.

The problem this lesson solves

Every web framework — Django, FastAPI, Flask — starts with the same two questions: How do I install it? and How do I make it respond to a URL? Without a clear answer, you end up fighting your own environment instead of building features.

The core problem is that a Python script and a web application are fundamentally different animals. A script runs top-to-bottom and quits. A web app stays alive, listening for requests on a network port, and responds based on the URL path and method (GET, POST, etc.). If you've never set up a web server, the concept of "binding to localhost:5000" can feel like magic — and magic is where bugs hide.

This lesson removes that magic. You'll learn the precise, minimal steps to install Flask and create a first route, so you can move from "script thinking" to "web thinking." This is the same pattern you'll use for every route you add later in this track: a function in Python, decorated with a URL, returning a response.

Core concept / mental model

Think of Flask as a switchboard operator for your Python code. When a request comes in (a visitor types a URL in their browser), Flask looks at the URL and the HTTP method, then routes that request to the correct Python function — the one you've flagged with a @app.route() decorator.

In the diagram above, the browser sends GET / to Flask. Flask matches that route to the Python function index(), runs it, and sends back the returned string. The key idea: a route is a mapping between a URL pattern and a Python function.

Let's define the terms you'll see everywhere in Flask docs:

• Route — a URL pattern (e.g., /, /about) that the app listens for.
• View function — the Python function that runs when a route is matched.
• Decorator — @app.route("/") attaches URL information to the function below it.
• Development server — Flask's built-in web server (app.run()) for local testing.
• Virtual environment — an isolated directory for your project's dependencies (we'll use one now, it saves you from dependency hell later).

The mental model to hold onto: Flask doesn't serve your whole Python script at once. It only runs the specific view function that matches the incoming request. That's how a single app can handle dozens of URLs without re-running the entire file.

How it works step by step

Now let's walk through the exact steps you'll take to install Flask and create a first route. This is the "cause → effect" sequence that gets a working web app.

1. Set up a virtual environment — This isolates your project dependencies. Use python -m venv venv (or python3 on Linux/macOS).
2. Activate the environment — On Windows: venv\Scripts\activate; on macOS/Linux: source venv/bin/activate. Your terminal prompt shows (venv) when it's active.
3. Install Flask — pip install flask pulls in Flask and a few small dependencies (Werkzeug, Jinja2, etc.).
4. Create your app file — Typically app.py or hello.py. Import Flask, create an app instance, and define a route.
5. Run the development server — python app.py or flask run (we'll use the first). The server prints a URL like http://127.0.0.1:5000.
6. Visit the URL in your browser — You should see the text your view function returned.

Each step builds on the last; the cause of a successful "Hello, World!" is the effect of a properly activated virtual environment and a correct route setup. Miss step 1 or 2, and you'll likely get a ModuleNotFoundError: No module named 'flask'.

Step-by-step mechanics: - When you call Flask(__name__), the __name__ argument helps Flask find resources like templates and static files relative to your app. - The @app.route("/") decorator registers the function in Flask's internal URL map. - When a request matches, Flask calls the function with the request context, and whatever the function returns becomes the HTTP response body.

Hands-on walkthrough

Time to get your hands dirty. We'll create a minimal application with one route, run it, and see the result.

Step 1: Set up your project directory and virtual environment

Open a terminal and run:

mkdir flask-hello
cd flask-hello
python -m venv venv

Step 2: Activate the virtual environment

On macOS/Linux:

source venv/bin/activate

On Windows (Command Prompt):

venv\Scripts\activate

Your terminal prompt should now show (venv) at the start. If it doesn't, you've skipped this step.

Step 3: Install Flask

With the environment active, run:

pip install flask

You'll see output showing the installed packages. To verify, you can check the version:

python -c "import flask; print(flask.__version__)"

Expected output (the exact version may vary):

2.3.3

Step 4: Create your first Flask app

Now create a file named app.py in the same directory. Copy this complete example:

from flask import Flask

# Create the Flask application instance
app = Flask(__name__)

# Define the first route: the root URL "/"
@app.route("/")
def index():
    return "Hello, Flask!"

# Run the development server if this script is executed directly
if __name__ == "__main__":
    app.run(debug=True)

Step 5: Run the app

In your terminal (with the virtual environment still active), run:

python app.py

Expected output:

 * Serving Flask app 'app'
 * Debug mode: on
 * Running on http://127.0.0.1:5000 (Press CTRL+C to quit)
 * Restarting with stat
 * Debugger is active!

Now open your browser and go to http://127.0.0.1:5000. You should see:

Hello, Flask!

Congratulations — you just installed Flask and created a first route! The server is listening for requests, and your index() function is being called every time someone visits the root URL.

Step 6: Add a second route (optional sneak preview)

To see how routes scale, add another route for /about:

@app.route("/about")
def about():
    return "About this Flask app."

Restart the server (Ctrl+C, then python app.py again) and visit http://127.0.0.1:5000/about. You'll see the new message. The pattern is identical: a decorator, a function, a return value.

Compare options / when to choose what

You've installed Flask via pip, but there are a few decisions you'll face. Here's a comparison to help you choose wisely.

Virtual environment vs. global install

Recommendation: Use a virtual environment. It's the industry best practice and the first thing recruiters and senior devs look for.

flask run vs. python app.py

Both work for a beginner. In this lesson we used python app.py for clarity — but once you're comfortable, switch to flask run for real projects.

Alternative: FastAPI or Django

This track uses Flask, but it's worth noting the landscape:

• Flask — Microframework, minimal, great for learning routing and HTTP fundamentals.
• FastAPI — Modern async, automatic OpenAPI docs; excellent for building APIs, but requires learning type hints and async early.
• Django — "Batteries included": ORM, admin panel, auth; steep learning curve if you haven't mastered routing.

For this lesson, Flask is the right choice because it keeps routing visible and understandable. Later, you can transfer the same mental model to any framework.

Troubleshooting & edge cases

Even with clear instructions, things go wrong. Here are the most common issues you'll hit — and the fixes.

ModuleNotFoundError: No module named 'flask'

This almost always means the virtual environment isn't active. Check your terminal prompt for (venv). If it's missing, activate it again. If it's active but the error persists, you might have installed Flask in a different environment (e.g., a system Python). Run which pip on Linux/macOS or where pip on Windows to see which pip you're using.

Port already in use

If you see OSError: [Errno 98] Address already in use (Linux/macOS) or OSError: [WinError 10013] (Windows), another process is on port 5000. Two fixes: - Find and kill the process (e.g., lsof -i :5000 on macOS/Linux). - Change the port in app.run(port=5001) and visit http://127.0.0.1:5001.

Browser shows 404 Not Found

If you visit http://127.0.0.1:5000/nonexistent, Flask returns a 404 because there's no route for that path. That's expected. But if you typed the correct URL and still get 404, double-check that you saved your file and restarted the server after making changes.

Debugger off vs. on

If you set debug=True, you get auto-reload and a detailed error page — great for development. But in production, never run with debug=True; it exposes sensitive information. For now, keep it on for learning.

Using the wrong Python interpreter

If you're still inside the virtual environment but python --version shows an unexpected version, you may have a corrupted environment. Recreate it:

rm -rf venv
python -m venv venv
source venv/bin/activate  # or Windows activation
pip install flask

Edge case: Silent server start but no response in browser

This can happen if your firewall blocks the port or if you're using a remote server. In that case, bind to 0.0.0.0 temporarily to test: app.run(host="0.0.0.0"). But never do that in production without a reverse proxy.

What you learned & what's next

Let's recap what you accomplished:

• You understood the core idea of Flask routing: how @app.route() maps URLs to Python functions.
• You installed Flask in a virtual environment, following industry best practices.
• You created a first route (/) that returns a response, and you added a second route (/about).
• You ran the development server and interacted with your app over HTTP.
• You can now troubleshoot common installation and routing errors.

This is the foundation everything else builds on. In the next lesson, you'll learn about routes with parameters — how to capture dynamic values from the URL (like /user/<username>) and use them in your view functions. That's the next step toward building real, data-driven web apps.

Keep your virtual environment active and your app.py ready — you'll extend it in the next lesson.

Pro tip: Always commit your requirements.txt (generate it with pip freeze > requirements.txt) so your project is reproducible. You'll thank yourself when you work on a new machine or with a teammate.