Flask is a lightweight and flexible web framework for Python that is perfect for beginners. This guide will walk you through installing Flask, setting up a basic web app, and troubleshooting common errors.
Step 1: Install Python
Why?
Flask is a Python framework, so you need Python installed on your machine.
How?
-
- Check if Python is installed:
Open your terminal (Command Prompt, Powershell, Terminal):
bash
python –versionor
bash
python3 –versionIf you see a version number (e.g., Python 3.9.7), Python is installed.
- Check if Python is installed:
-
- If Python is not installed:
-
- Download from python.org
-
- Follow the installation instructions.
-
- Ensure you check the box “Add Python to PATH” during installation (important for using Python from the command line).
-
- If Python is not installed:
Step 2: Create a Virtual Environment (Recommended)
Why?
A virtual environment isolates your project and its dependencies from global Python installations.
How?
-
- Create a folder for your project:
bash
mkdir flask_project
cd flask_project
- Create a folder for your project:
-
- Create a virtual environment:
bash
python -m venv venvor, if your system uses
python3
:
bash
python3 -m venv venv
- Create a virtual environment:
-
- Activate the virtual environment:
-
- On Windows (Command Prompt):
venv\Scripts\activate
-
- On macOS/Linux:
source venv/bin/activate
-
- Activate the virtual environment:
-
- You should now see
(venv)
at the start of your terminal prompt indicating the environment is active.
- You should now see
Step 3: Install Flask
Why?
You need to install the Flask package inside your virtual environment.
How?
-
- Run:
bash
pip install Flask
- Run:
Troubleshooting:
-
- If
pip
is not recognized:-
- Ensure your virtual environment is activated.
-
- Use
python -m pip install Flask
as an alternative.
- Use
-
- If
-
- If you get permissions errors, make sure you are not using
sudo
or running outside a virtual environment.
- If you get permissions errors, make sure you are not using
Step 4: Create Your First Flask Application
How?
-
- Inside your project folder, create a new Python file, e.g.,
app.py
.
- Inside your project folder, create a new Python file, e.g.,
-
- Open
app.py
in a text editor and paste the following starter code:
- Open
python
from flask import Flask
app = Flask(name)
@app.route(‘/’)
def home():
return “Hello, Flask!”
if name == “main“:
app.run(debug=True)
-
- Explanation:
-
Flask(__name__)
initializes the app.
-
@app.route('/')
creates a route for the homepage.
-
app.run(debug=True)
starts the server with debug mode on (helpful for catching errors).
-
- Explanation:
Step 5: Run Your Flask Application
How?
-
- Make sure your virtual environment is activated.
-
- Run the file:
bash
python app.pyor if your system requires:
bash
python3 app.py
- Run the file:
-
- You should see output like:
-
- Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
-
- Restarting with stat
-
- Debugger is active!
-
- Debugger PIN: 123-456-789
-
- You should see output like:
-
- Open your web browser and visit
http://127.0.0.1:5000/
.
- Open your web browser and visit
-
- You should see the text: Hello, Flask!
Step 6: Common Errors & How to Fix Them
1. ModuleNotFoundError: No module named ‘flask’
-
- Cause: Flask is not installed in your current environment.
-
- Fix:
-
- Ensure virtual environment is activated (
(venv)
prefix).
- Ensure virtual environment is activated (
-
- Run
pip install Flask
.
- Run
-
- Verify installation with
pip list
and look for Flask.
- Verify installation with
-
- Fix:
2. ‘python’ is not recognized as an internal or external command
-
- Cause: Python is not added to your PATH environment variable.
-
- Fix:
-
- Reinstall Python and check “Add Python to PATH” option.
-
- Alternatively, use full Python path or edit the Path variable manually.
-
- Fix:
3. Port 5000 already in use
-
- Sometimes another app is using Flask’s default port.
-
- Fix:
-
- Run Flask on a different port, e.g.:
bash
python app.py –port=5001
- Run Flask on a different port, e.g.:
Or edit
app.run()
:
python
app.run(debug=True, port=5001) -
- Fix:
4. IndentationError or SyntaxError
-
- Python is sensitive to indentation.
-
- Make sure your code is properly indented (4 spaces per indentation level).
-
- Avoid mixing tabs and spaces.
Step 7: Next Steps
-
- Start building more routes and templates.
-
- Learn how to:
-
- Use HTML templates with Jinja2 (
render_template()
).
- Use HTML templates with Jinja2 (
-
- Handle form submissions.
-
- Connect to a database.
-
- Organize your Flask project structure.
-
- Learn how to:
Additional Tips
-
- Always activate the virtual environment when working on your project.
-
- Use
pip freeze > requirements.txt
to save dependencies.
- Use
-
- Share your
requirements.txt
so others can install dependencies with:
bash
pip install -r requirements.txt
- Share your