This tutorial is out of date and no longer maintained.
Flask is a simple, easy-to-use microframework for Python that can help build scalable and secure web applications. Here are a few reasons why Flask is great for beginners:
In this tutorial, we’ll cover the following:
By the end of this tutorial, we will have built a simple static website using Flask. The code used in this tutorial is available for your reference on GitHub.
Ready? Let’s dive in!
We’ll need the following installed for this tutorial:
You may already have Python installed on your system. You can check by running the python
command in your terminal. If it’s installed, you should see the following output:
Python 2.7.10 (default, Oct 23 2015, 19:19:21)
[GCC 4.2.1 Compatible Apple LLVM 7.0.0 (clang-700.0.59.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>
If you don’t have it installed, you can download it here.
We’ll start by installing virtualenv, a tool to create isolated Python environments. We need to use virtual environments to keep the dependencies used by different Python projects separate, and to keep our global site-packages directory clean. We’ll go one step further and install virtualenvwrapper, a set of extensions that make using virtualenv a whole lot easier by providing simpler commands.
To create and activate a virtualenv, run the following commands:
Told you the commands were simple! We now have a virtualenv called my-venv
, which we have activated and are currently working on. Now, any dependencies we install will be installed here and not globally. Remember to activate the virtualenv whenever you want to use or work on this project!
Next, let’s create a directory for our app. This is where all our files will go:
Finally, let’s install Flask:
Installing Flask also installs a few other dependencies, which you will see when you run the following command:
click==6.6
Flask==0.11.1
itsdangerous==0.24
Jinja2==2.8
MarkupSafe==0.23
Werkzeug==0.11.11
What do all these packages do? Flask uses Click (Command Line Interface Creation Kit) for its command-line interface, which allows you to add custom shell commands for your app. ItsDangerous provides security when sending data using cryptographical signing. Jinja2 is a powerful template engine for Python, while MarkupSafe is an HTML string handling library. Werkzeug is a utility library for WSGI, a protocol that ensures web apps and web servers can communicate effectively.
You can save the output above in a file. This is good practice because anyone who wants to work on or run your project will need to know the dependencies to install. The following command will save the dependencies in a requirements.txt
file:
I think any beginner programming tutorial would be remiss if it didn’t start with the classic “Hello World!” So here’s how to do this in Flask:
Create the following file, hello_world.py
, in your favorite text editor (I’m an Atom girl, myself):
We begin by importing the Flask
class and creating an instance of it. We use the __name__
argument to indicate the app’s module or package so that Flask knows where to find other files such as templates. Then we have a simple function that will display the string Hello World!
. The preceding decorator simply tells Flask which path to display the result of the function. In this case, we have specified the route /
, which is the home URL.
Let’s see this in action, shall we? In your terminal, run the following:
* Serving Flask app "hello_world"
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
The first command tells the system which app to run. The next one starts the server. Enter the specified URL (http://127.0.0.1:5000/
) in your browser. Voila! It works!
So far, we only have one functional file in our project: hello_world.py
. A real-world web project usually has more files than that. It’s important to maintain a good directory structure, so as to organize the different components of the application separately. These are a few of the common directories in a Flask project:
/app
: This is a directory within my-project
. We’ll put all our code in here, and leave other files, such as the requirements.txt
file, outside./app/templates
: This is where our HTML files will go./app/static
: This is where static files such as CSS and JavaScript files as well as images usually go. However, we won’t be needing this folder for this tutorial since we won’t be using any static files.Your project directory should now look like this:
The hello_world.py
seems a little out of place now, doesn’t it? Don’t worry, we’ll fix that in the next section.
For the “Hello World!” example, we only had one file. To build our website, we’ll need more files that serve various functions. Most Flask apps have the following basic file structure:
run.py
: This is the application’s entry point. We’ll run this file to start the Flask server and launch our application.config.py
: This file contains the configuration variables for your app, such as database details.app/__init__.py
: This file initializes a Python module. Without it, Python will not recognize the app
directory as a module.app/views.py
: This file contains all the routes for our application. This will tell Flask what to display on which path.app/models.py
: This is where the models are defined. A model is a representation of a database table in code. However, because we will not be using a database in this tutorial, we won’t be needing this file.Some projects have more modules (for example, an app/views
directory with many views files in it), but this will do for now. Go ahead and create these files, and delete hello_world.py
since we won’t be needing it anymore:
Here’s our latest directory structure:
├── my-project
├── app
│ ├── __init__.py
│ ├── templates
│ └── views.py
├── config.py
├── requirements.txt
└── run.py
Now let’s fill these empty files with some code!
The config.py
file should contain one variable per line, like so:
Note that this config file is very simplified and would not be appropriate for a more complex application. For bigger applications, you may choose to have different config.py
files for testing, development, and production, and put them in a config
directory, making use of classes and inheritance. You may have some variables that should not be publicly shared, such as passwords and secret keys. These can be put in an instance/config.py
file, which should not be pushed to version control.
Next, we have to initialize our app with all our configurations. This is done in the app/__init__.py
file. Note that if we set instance_relative_config
to True
, we can use app.config.from_object('config')
to load the config.py
file.
All we have to do now is configure our run.py
file so we can start the Flask server.
To use the command flask run
as we did before, we would need to set the
FLASK_APP
environment variable to run.py
, like so:
We’ll get a 404 page because we haven’t written any views for our app. We’ll be fixing that shortly.
From the “Hello World!” example, you already have an understanding of how views work. We use the @app.route
decorator to specify the path we’d like the view to be displayed on. We’ve already seen how to write a view that returns a string. Let’s see what else we can do with views.
Flask provides a method, render_template
, which we can use to specify which HTML file should be loaded in a particular view. Of course, the index.html
and about.html
files don’t exist yet, so Flask will give us a Template Not Found
error when we navigate to these paths. Go ahead; run the app and see:
Flask allows us to use a variety of template languages, but Jinja2 is by far the most popular one. Remember it from our installed dependencies? Jinja provides syntax that allows us to add some functionality to our HTML files, like if-else
blocks and for
loops, and also use variables inside our templates. Jinja also lets us implement template inheritance, which means we can have a base template that other templates inherit from. Cool, right?
Let’s begin by creating the following three HTML files:
We’ll start with the base.html
file, using a slightly modified version of this example Bootstrap template:
Did you notice the {% block %}
and {% endblock %}
tags? We’ll also use them in the templates that inherit from the base template:
We use the {% extends %}
tag to inherit from the base template. We insert the dynamic content inside the {% block %}
tags. Everything else is loaded right from the base template, so we don’t have to re-write things that are common to all pages, such as the navigation bar and the footer.
Let’s refresh our browser and see what we have now:
Congratulations for making it this far and getting your first Flask website up and running! I hope this introduction to Flask has whetted your appetite for exploring more. You now have a great foundation to start building more complex apps. Do have a look at the official documentation for more information.
Have you used other Python frameworks before? Where do you think Flask stands? Let’s have a conversation in the comments below.
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
This textbox defaults to using Markdown to format your answer.
You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!