Skip to main content
Making your project installable means you can build a distribution file and install it in another environment, just like you installed Flask. This makes deploying your project the same as installing any other library.

​
Benefits of Making Your Project Installable

Installing comes with several benefits:
  1. Import from anywhere - Python and Flask can use the flaskr package no matter where you run from, not just from your project’s directory
  2. Dependency management - You can manage your project’s dependencies just like other packages do, so pip install yourproject.whl installs them
  3. Test isolation - Test tools can isolate your test environment from your development environment
This is being introduced late in the tutorial, but in your future projects you should always start with this.

​
Describe the Project

1

Create pyproject.toml

The pyproject.toml file describes your project and how to build it.Create pyproject.toml in the project root:
pyproject.toml
[project]
name = "flaskr"
version = "1.0.0"
description = "The basic blog app built in the Flask tutorial."
dependencies = [
    "flask",
]

[build-system]
requires = ["flit_core<4"]
build-backend = "flit_core.buildapi"
Configuration breakdown:
  • name - The package name that will be used when installing
  • version - The current version of your application
  • description - A brief description of what your application does
  • dependencies - List of packages your project needs (Flask in this case)
  • build-system - Specifies how to build the distribution file
2

Add test configuration (optional)

You can add configuration for pytest and coverage tools:
pyproject.toml
[project.optional-dependencies]
test = ["pytest", "coverage"]

[tool.pytest.ini_options]
testpaths = ["tests"]

[tool.coverage.run]
branch = true
source = ["flaskr"]
See the official Python Packaging tutorial for more explanation of the files and options used.

​
Install the Project

1

Install in editable mode

Use pip to install your project in the virtual environment:
pip install -e .
This tells pip to find pyproject.toml in the current directory and install the project in editable or development mode.Editable mode means that as you make changes to your local code, you’ll only need to re-install if you change the metadata about the project, such as its dependencies.
2

Verify the installation

You can observe that the project is now installed with pip list:
pip list
Output:
Package        Version   Location
-------------- --------- ----------------------------------
click          8.1.7
Flask          3.0.0
flaskr         1.0.0     /home/user/Projects/flask-tutorial
itsdangerous   2.1.2
Jinja2         3.1.2
MarkupSafe     2.1.3
pip            23.3.1
Werkzeug       3.0.1

​
Running the Application

Nothing changes from how you’ve been running your project so far: 
flask --app flaskr run --debug
However, you can now call it from anywhere, not just the flask-tutorial directory.

​
Building a Distribution File

When you want to deploy your application elsewhere, you build a wheel (.whl) file:
1

Install build tool

pip install build
2

Build the wheel

python -m build --wheel
This creates a file in dist/flaskr-1.0.0-py3-none-any.whl.
The file name format is: 
{project name}-{version}-{python tag}-{abi tag}-{platform tag}

​
Installing on Another Machine

1

Copy the wheel file

Copy dist/flaskr-1.0.0-py3-none-any.whl to another machine.
2

Set up virtual environment

On the other machine, create a new virtual environment:
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
3

Install the wheel

pip install flaskr-1.0.0-py3-none-any.whl
Pip will install your project along with its dependencies.
4

Initialize the database

Since this is a different machine, you need to run init-db again:
flask --app flaskr init-db
5

Run the application

flask --app flaskr run

​
Instance Folder Location

When Flask detects that it’s installed (not in editable mode), it uses a different directory for the instance folder:
  • Development (editable): flask-tutorial/instance/
  • Installed: .venv/var/flaskr-instance/
This keeps configuration and database files separate from your code.

​
Project Structure Summary

Your final installable project structure: 
flask-tutorial/
├── flaskr/
│   ├── __init__.py
│   ├── auth.py
│   ├── blog.py
│   ├── db.py
│   ├── schema.sql
│   ├── static/
│   │   └── style.css
│   └── templates/
│       ├── base.html
│       ├── auth/
│       │   ├── login.html
│       │   └── register.html
│       └── blog/
│           ├── create.html
│           ├── index.html
│           └── update.html
├── tests/
│   └── ...
├── .venv/
├── pyproject.toml
└── README.md
Now your application is properly packaged and can be installed on any system with Python. The next step is to add comprehensive tests.

Build docs developers (and LLMs) love

Get started for freeTalk to us