The Flask Mega-Tutorial Part I: Hello, World!
Posted byon under
Welcome! You are about to start on a journey to learn how to create web applications with Python and the Flask framework. In this first chapter, you are going to learn how to set up a Flask project. By the end of this chapter you are going to have a simple Flask web application running on your computer!
For your reference, below is a list of the articles in this series.
- Chapter 1: Hello, World! (this article)
- Chapter 2: Templates
- Chapter 3: Web Forms
- Chapter 4: Database
- Chapter 5: User Logins
- Chapter 6: Profile Page and Avatars
- Chapter 7: Error Handling
- Chapter 8: Followers
- Chapter 9: Pagination
- Chapter 10: Email Support
- Chapter 11: Facelift
- Chapter 12: Dates and Times
- Chapter 13: I18n and L10n
- Chapter 14: Ajax
- Chapter 15: A Better Application Structure
- Chapter 16: Full-Text Search
- Chapter 17: Deployment on Linux
- Chapter 18: Deployment on Heroku
- Chapter 19: Deployment on Docker Containers
- Chapter 21: User Notifications
- Chapter 22: Background Jobs
- Chapter 23: Application Programming Interfaces (APIs)
All the code examples presented in this book are hosted on a GitHub repository. Downloading the code from GitHub can save you a lot of typing, but I strongly recommend that you type the code yourself, at least for the first few chapters. Once you become more familiar with Flask and the example application you can access the code directly from GitHub if the typing becomes too tedious.
At the beginning of each chapter, I'm going to give you three GitHub links that can be useful while you work through the chapter. The Browse link will open the GitHub repository for Microblog at the place where the changes for the chapter you are reading were added, without including any changes introduced in future chapters. The Zip link is a download link for a zip file including the entire application up to and including the changes in the chapter. The Diff link will open a graphical view of all the changes that were made in the chapter you are about to read.
The GitHub links for this chapter are: Browse, Zip, Diff.
If you don't have Python installed on your computer, go ahead and install it now. If your operating system does not provide you with a Python package, you can download an installer from the Python official website. If you are using Microsoft Windows along with WSL or Cygwin, note that you will not be using the Windows native version of Python, but a Unix-friendly version that you need to obtain from Ubuntu (if you are using WSL) or from Cygwin.
To make sure your Python installation is functional, you can open a terminal window and type
python3, or if that does not work, just
python. Here is what you should expect to see:
$ python3 Python 3.9.6 (default, Jul 10 2021, 16:13:29) [Clang 12.0.0 (clang-1220.127.116.11)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> _
The Python interpreter is now waiting at an interactive prompt, where you can enter Python statements. In future chapters you will learn what kinds of things this interactive prompt is useful for. But for now, you have confirmed that Python is installed on your system. To exit the interactive prompt, you can type
exit() and press Enter. On the Linux and Mac OS X versions of Python you can also exit the interpreter by pressing Ctrl-D. On Windows, the exit shortcut is Ctrl-Z followed by Enter.
The next step is to install Flask, but before I go into that I want to tell you about the best practices associated with installing Python packages.
In Python, packages such as Flask are available in a public repository, from where anybody can download them and install them. The official Python package repository is called PyPI, which stands for Python Package Index (some people also refer to this repository as the "cheese shop"). Installing a package from PyPI is very simple, because Python comes with a tool called
pip that does this work.
To install a package on your machine, you use
pip as follows:
$ pip install <package-name>
Interestingly, this method of installing packages will not work in most cases. If your Python interpreter was installed globally for all the users of your computer, chances are your regular user account is not going to have permission to make modifications to it, so the only way to make the command above work is to run it from an administrator account. But even without that complication, consider what happens when you install a package as above. The
pip tool is going to download the package from PyPI, and then add it to your Python installation. From that point on, every Python script that you have on your system will have access to this package. Imagine a situation where you have completed a web application using version 1.1 of Flask, which was the most current version of Flask when you started, but now has been superseded by version 2.0. You now want to start a second application, for which you'd like to use the 2.0 version, but if you replace the 1.1 version that you have installed you risk breaking your older application. Do you see the problem? It would be ideal if it was possible to have Flask 1.1 installed and accessible to your old application, while also install Flask 2.0 for your new one.
To address the issue of maintaining different versions of packages for different applications, Python uses the concept of virtual environments. A virtual environment is a complete copy of the Python interpreter. When you install packages in a virtual environment, the system-wide Python interpreter is not affected, only the copy is. So the solution to have complete freedom to install any versions of your packages for each application is to use a different virtual environment for each application. Virtual environments have the added benefit that they are owned by the user who creates them, so they do not require an administrator account.
Let's start by creating a directory where the project will live. I'm going to call this directory microblog, since that is the name of the application:
$ mkdir microblog $ cd microblog
Support for virtual environments is included in all recent versions of Python, so all you need to do to create one is this:
$ python3 -m venv venv
With this command, I'm asking Python to run the
venv package, which creates a virtual environment named
venv. The first
venv in the command is the name of the Python virtual environment package, and the second is the virtual environment name that I'm going to use for this particular environment. If you find this confusing, you can replace the second
venv with a different name that you want to assign to your virtual environment. In general I create my virtual environments with the name
venv in the project directory, so whenever I
cd into a project I find its corresponding virtual environment.
Note that in some operating systems you may need to use
python instead of
python3 in the command above. Some installations use
python for Python 2.x releases and
python3 for the 3.x releases, while others map
python to the 3.x releases.
After the command completes, you are going to have a directory named venv where the virtual environment files are stored.
Now you have to tell the system that you want to use this virtual environment, and you do that by activating it. To activate your brand new virtual environment you use the following command:
$ source venv/bin/activate (venv) $ _
If you are using a Microsoft Windows command prompt window, the activation command is slightly different:
$ venv\Scripts\activate (venv) $ _
When you activate a virtual environment, the configuration of your terminal session is modified so that the Python interpreter stored inside it is the one that is invoked when you type
python. Also, the terminal prompt is modified to include the name of the activated virtual environment. The changes made to your terminal session are all temporary and private to that session, so they will not persist when you close the terminal window. If you work with multiple terminal windows open at the same time, it is perfectly fine to have different virtual environments activated on each one.
Now that you have a virtual environment created and activated, you can finally install Flask in it:
(venv) $ pip install flask
If you want to confirm that your virtual environment now has Flask installed, you can start the Python interpreter and import Flask into it:
>>> import flask >>> _
If this statement does not give you any errors you can congratulate yourself, as Flask is installed and ready to be used.
Note that the above installation commands does not specify which version of Flask you want to install. The default when no version is specified is to install the latest version available in the package repository. This tutorial can be followed with Flask versions 1 and 2. The above command will install the latest 2.x version. If for any reason you prefer to follow this tutorial on a 1.x release of Flask, you can use the following command to install the latest 1.x version:
(venv) $ pip install "flask<2"
A "Hello, World" Flask Application
If you go to the Flask website, you are welcomed with a very simple example application that has just five lines of code. Instead of repeating that trivial example, I'm going to show you a slightly more elaborate one that will give you a good base structure for writing larger applications.
The application will exist in a package. In Python, a sub-directory that includes a __init__.py file is considered a package, and can be imported. When you import a package, the __init__.py executes and defines what symbols the package exposes to the outside world.
Let's create a package called
app, that will host the application. Make sure you are in the microblog directory and then run the following command:
(venv) $ mkdir app
The __init__.py for the
app package is going to contain the following code:
app/__init__.py: Flask application instance
from flask import Flask app = Flask(__name__) from app import routes
The script above simply creates the application object as an instance of class
Flask imported from the flask package. The
__name__ variable passed to the
Flask class is a Python predefined variable, which is set to the name of the module in which it is used. Flask uses the location of the module passed here as a starting point when it needs to load associated resources such as template files, which I will cover in Chapter 2. For all practical purposes, passing
__name__ is almost always going to configure Flask in the correct way. The application then imports the
routes module, which doesn't exist yet.
One aspect that may seem confusing at first is that there are two entities named
app package is defined by the app directory and the __init__.py script, and is referenced in the
from app import routes statement. The
app variable is defined as an instance of class
Flask in the __init__.py script, which makes it a member of the
Another peculiarity is that the
routes module is imported at the bottom and not at the top of the script as it is always done. The bottom import is a workaround to circular imports, a common problem with Flask applications. You are going to see that the
routes module needs to import the
app variable defined in this script, so putting one of the reciprocal imports at the bottom avoids the error that results from the mutual references between these two files.
So what goes in the
routes module? The routes are the different URLs that the application implements. In Flask, handlers for the application routes are written as Python functions, called view functions. View functions are mapped to one or more route URLs so that Flask knows what logic to execute when a client requests a given URL.
Here is the first view function for this application, which you need to write in a new module named app/routes.py:
app/routes.py: Home page route
from app import app @app.route('/') @app.route('/index') def index(): return "Hello, World!"
This view function is actually pretty simple, it just returns a greeting as a string. The two strange
@app.route lines above the function are decorators, a unique feature of the Python language. A decorator modifies the function that follows it. A common pattern with decorators is to use them to register functions as callbacks for certain events. In this case, the
@app.route decorator creates an association between the URL given as an argument and the function. In this example there are two decorators, which associate the URLs
/index to this function. This means that when a web browser requests either of these two URLs, Flask is going to invoke this function and pass the return value of it back to the browser as a response. If this does not make complete sense yet, it will in a little bit when you run this application.
To complete the application, you need to have a Python script at the top-level that defines the Flask application instance. Let's call this script microblog.py, and define it as a single line that imports the application instance:
microblog.py: Main application module
from app import app
Remember the two
app entities? Here you can see both together in the same sentence. The Flask application instance is called
app and is a member of the
app package. The
from app import app statement imports the
app variable that is a member of the
app package. If you find this confusing, you can rename either the package or the variable to something else.
Just to make sure that you are doing everything correctly, below you can see a diagram of the project structure so far:
microblog/ venv/ app/ __init__.py routes.py microblog.py
Believe it or not, this first version of the application is now complete! Before running it, though, Flask needs to be told how to import it, by setting the
FLASK_APP environment variable:
(venv) $ export FLASK_APP=microblog.py
If you are using the Microsoft Windows command prompt, use
set instead of
export in the command above.
Are you ready to be blown away? You can run your first web application, with the following command:
(venv) $ flask run * Serving Flask app 'microblog.py' (lazy loading) * Environment: production WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead. * Debug mode: off * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
After the server initializes it will wait for client connections. The output from
flask run indicates that the server is running on IP address 127.0.0.1, which is always the address of your own computer. This address is so common that is also has a simpler name that you may have seen before: localhost. Network servers listen for connections on a specific port number. Applications deployed on production web servers typically listen on port 443, or sometimes 80 if they do not implement encryption, but access to these ports requireis administration rights. Since this application is running in a development environment, Flask uses the freely available port 5000. Now open up your web browser and enter the following URL in the address field:
Alternatively you can use this other URL:
Do you see the application route mappings in action? The first URL maps to
/, while the second maps to
/index. Both routes are associated with the only view function in the application, so they produce the same output, which is the string that the function returns. If you enter any other URL you will get an error, since only these two URLs are recognized by the application.
When you are done playing with the server you can just press Ctrl-C to stop it.
Congratulations, you have completed the first big step to become a web developer!
Before I end this chapter, I will do one more thing. Since environment variables aren't remembered across terminal sessions, you may find tedious to always have to set the
FLASK_APP environment variable when you open a new terminal window. Starting with version 1.0, Flask allows you to register environment variables that you want to be automatically imported when you run the
flask command. To use this option you have to install the python-dotenv package:
(venv) $ pip install python-dotenv
Then you can just write the environment variable name and value in a file named .flaskenv located in the top-level directory of the project:
.flaskenv: Environment variables for flask command
Become a Patron!
Hello, and thank you for visiting my blog! If you enjoyed this article, please consider supporting my work on this blog on Patreon!
#26 Elmer Thomas said 2017-12-19T21:42:54Z
Thank you so much for this!
I learned how to Flask with your first Mega Tutorial and then polished my skills through your O'Reilly book :)
I have one request. Given the popularity of AWS, how about a section on deploying there? Particularly, how can we leverage Lambda with respect to Flask. I've been recently inspired by www.testdriven.io in that regard.
Alternatively, since there are many clouds to deploy to, there can be a section (which you promote) in your repo where contributors can submit PRs that demonstrate deploy strategies for the most popular services.
With Best Regards,
#27 Miguel Grinberg said 2017-12-20T06:05:34Z
@Brett: The main (and only really) reason I rewrote the tutorial is to address several problems with the original tutorial. You can try it if you like, but it's not going to be a smooth experience, more so if you are using Python 3.
#28 Miguel Grinberg said 2017-12-20T06:13:42Z
@Elmer: Thanks. At this time the structure of the tutorial is finalized, I have allowed people to propose topics and even vote on them during the Kickstarter period, and deployment to Lambda/API Gateway was there, but other topics got more votes. There is a chapter on Linux deployment that can be applied to EC2, and another chapter on Docker which can be applied to ECS, so AWS coverage is fair, in my opinion.
#29 Carsten Henek said 2017-12-26T23:39:17Z
Thanks man for this tutorial.
I made it in one try :)
#30 ikukuVision said 2017-12-27T01:44:20Z
Hi Miguel. Just a quick one, I have a query with regards to Unit Testing the User Model. I saved tests.py in my main app directory, but I'm getting the error: Python: can't open file 'tests.py': [Errno 2] No such file or directory. Have i saved it in the wrong location? Sorry to ask here, but I am not sure where else i should. Thanks again.
#31 Miguel Grinberg said 2017-12-28T07:25:18Z
@ikukuVision: The tests.py module goes in the top-level directory, it is not part of the app package.
#32 ikukuVision said 2017-12-28T12:07:38Z
Thanks Miguel. I was able to resolve it, but i couldn't find my original comment to delete or retract. Please may i ask if there will be any sort of forum eventually attached to this?
I've been stuck on a [werkzeug.routing.BuildError: Could not build url for endpoint 'user' with values ['username']. Did you mean 'register' instead?] for 2 days. I've tried to debug on my own with StackOverflow and Google, but I've been unable to resolve it.
It will be nice to ask other users if they have surmounted this already, instead of constantly bothering you. I will appreciate any help from yourself of any other user who understands and can point me in the right direction. Thank you kindly
#33 Miguel Grinberg said 2017-12-28T16:53:30Z
@ikukuVision: doesn't StackOverflow work for questions about this tutorial? Some people already write questions there, I think it makes a lot more sense than asking me directly here on the blog.
#34 Jonathan Faber said 2018-01-01T15:53:08Z
On windows: After running
(venv) C:\Users\Jon\Documents\python\flask\microblog>set Flask_App=microblog.py
in 'Hello World' application, I run
(venv) C:\Users\Jon\Documents\python\flask\microblog>flask run
I get the error
'flask' is not recognized as an internal or external command,
operable program or batch file.
#35 Ben said 2018-01-01T22:30:11Z
Is there a reason why you didnt just do app.run() in microblog.py which then would make it unnecessary to do
$ export FLASK_APP=microblog.py
Also can you explain a little more the purpose of having this double structure of having a microblog folder with venv and microblog.py and then an app folder with routes and everything else...
Why not just have everything in the microblog folder or put everything in the app folder...after all, the app you are making IS microblog...
#36 Miguel Grinberg said 2018-01-02T06:21:09Z
@Jonathan: You are not setting the correct environment variable, use all uppercase letters and I think you will be fine.
#37 Miguel Grinberg said 2018-01-02T06:29:36Z
@Ben: The app.run() method of starting the server is not compatible with the Flask reloader, so it is not recommended anymore. See http://flask.pocoo.org/docs/0.12/server/#in-code.
#38 Julian said 2018-01-02T07:32:39Z
Hi, I know you explained it in the article but I'm still a bit confused when you talk about the two 'apps' since I only recognize one, why do you talk about two of them.
Thank you for everything
#39 David Lowry-Duda said 2018-01-02T20:15:37Z
@Bill: I also had a unicode problem, which ultimately was caused by a poorly set locale. I used
export LANG=C.UTF-8, and this resolved my encoding problems. Perhaps you might have slightly differently named unicode locales, but I suspect a similar solution might work.
And thank you @Miguel. I'll be buying the tutorial. Excellent work!
#40 Miguel Grinberg said 2018-01-02T22:45:09Z
@Julian: there is the "app" variable, and there is also the "app" directory/package. Some people find it confusing that these two are named "app". If you need to import the variable, you need to do "from app import app".
#41 Emmanuel said 2018-01-02T23:35:35Z
I completed the tutorial: very good work, thak you very much. The examples are clear and illustrate the points.
Under Debian Stretch, I have a problem:
error: invalid command 'bdist_wheel'
I tested various setups, and starting from a clean minimal debian Stretch install:
sudo apt-get install python3-pip
sudo apt-get install python3-venv
python3 -m venv venv
pip install flask
Building wheels for collected packages: itsdangerous, MarkupSafe
Running setup.py bdist_wheel for itsdangerous ... error
Complete output from command /home/viennet/microblog/venv/bin/python3 -u -c "import setuptools, tokenize;file='/tmp/pip-build-tggw4r8x/itsdangerous/setup.py';f=getattr(tokenize, 'open', open)(file);code=f.read().replace('\r\n', '\n');f.close();exec(compile(code, file, 'exec'))" bdist_wheel -d /tmp/tmpo_22w0y5pip-wheel- --python-tag cp35:
usage: -c [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
or: -c --help [cmd1 cmd2 ...]
or: -c --help-commands
or: -c cmd --help
error: invalid command 'bdist_wheel'
#42 Miguel Grinberg said 2018-01-03T17:40:57Z
@Emmanuel: That's odd, but in any case, if you run "pip install wheel" in your virtualenv, then the problem should be fixed, I think.
#43 Navneeth said 2018-01-06T21:38:44Z
Hello Miguel. Firstly, thanks for doing this tutorial series. Secondly, I hope you can offer clarification about the FLASK_APP environment variable. Am I correct in assuming that you ran the
flask runfrom the directory containing microblog.py? On my first try I received the same error that @ikukuVision posted initially. Turned out I was running the command from the app directory. It then worked when I ran it from one level up, or when I set FLASK_APP to the absolute path to microblog.py. Is this the expected behaviour?
If it helps, I'm on Windows 10, with Flask installed via pip inside a conda environment.
#44 Miguel Grinberg said 2018-01-07T00:34:26Z
@Navneeth: If you follow the instructions I provide in this tutorial things should work, regardless of operating system. You should not change your current directory, staying in the top level is recommended, so that the entire application package is visible as "app".
#45 Julio said 2018-01-08T17:54:14Z
Hi, thanks for the tutorial.
What happen if I use Windows native version of Python? Is the app going to work or it might crash?
#46 Miguel Grinberg said 2018-01-08T18:19:08Z
@Julio: The entire tutorial is compatible with the Windows version of Python, if you are asking me for advice, I think you'll have a smoother ride if you use the Ubuntu version of Python inside the WSL subsystem.
#47 Michael said 2018-01-13T16:13:01Z
I'm definitely going to purchase the ebook and I'm considering the videos. Roughly how many hours are the videos?
#48 Miguel Grinberg said 2018-01-14T03:06:12Z
@Michael: An average based on what I recorded so far is about 30 minutes per episode, so at 23 chapters that means 11-12 hours for the entire tutorial. For the first nine chapters I type and talk about every single line of code on screen. The rest of the chapters I download the code for each chapter from GitHub at the beginning to save time, and then walk you through the changes.
#49 Gang Chen said 2018-01-17T04:30:50Z
it seems like "set FLASK_APP microblog.py" doesn't work on windows power shell.
I found the solution from https://stackoverflow.com/questions/37826016/error-while-running-minimal-flask-application
you have to run "setx FLASK_APP microblog.py" first to save the parameter, then close and reopen powershell, you parameter then will be saved and loaded.
#50 Miguel Grinberg said 2018-01-17T06:33:42Z
@Gang: My instructions are for the original command prompt, not for Powershell. I honestly see no point in learning/using a Microsoft specific shell, given that now you have several options to run unix based shells.