Install Poetry and Flask on Ubuntu 24.04 – Step-by-Step Guide

Poetry is a free and open-source tool designed to manage dependencies and package Python projects efficiently. It provides a streamlined overview of your project’s dependency structure, simplifies dependency installation, and makes it easy to publish your project to PyPI.

This guide will walk you through installing Poetry using Pipx and configuring it to manage a Flask app on Ubuntu 24.04. You’ll also learn how to create a virtual environment and run your Flask project with Poetry and Gunicorn.

Requirements Before You Begin

• You are working on an Ubuntu 24.04 system.

Installing Poetry via Pipx on Ubuntu 24.04

Installing Poetry in an isolated environment is recommended to avoid conflicts between Poetry’s internal components and your system’s global Python packages. Use the steps below to set up Pipx and install Poetry:

1. Refresh the APT Repository

$ sudo apt update

2. Install Pipx

$ sudo apt install pipx -y

3. Add Pipx to Your System PATH

$ pipx ensurepath

4. Enable Auto-Completion for Pipx Commands

$ echo 'eval "$(register-python-argcomplete pipx)"' >> ~/.bashrc

5. Apply the Configuration Changes

$ source ~/.bashrc

6. Use Pipx to Install Poetry

$ pipx install poetry

After installation, your terminal should display something like the following:

installed package poetry 2.0.0, installed using Python 3.12.3 These apps are now globally available - poetry done! 

7. Check the Installed Poetry Version

$ poetry --version

The expected output will be similar to:

Poetry (version 2.0.0)

Starting a New Poetry Project for Flask Development

You can either initialize Poetry in an existing Python project or let it create a new one from scratch. Using Poetry to set up a fresh project ensures the proper structure and configuration are created automatically. Below are the steps to begin a new Poetry-managed Flask project.

1. Create a New Project Directory

$ poetry new flask-app

The command above generates a folder named flask-app and includes the following structure:

• flask_app: Contains an __init__.py file for your Flask application logic, modules, and support code.
• pyproject.toml: Defines project metadata, Poetry settings, and dependencies.
• README.md: A basic documentation template for your project.
• tests: Organizes and stores the project's test files.

Created package flask_app in flask-app

2. Move into the Project Directory

$ cd flask-app

Setting Up a Virtual Environment and Installing Flask

1. Choose the Python Interpreter

$ poetry env use python3

This command tells Poetry to use the system’s default Python 3 interpreter. If you want a specific version, you can run something like poetry env use python3.11, assuming that version is installed.

Creating virtualenv flask-app-vnQ3DaWl-py3.12 in /home/linuxuser/.cache/pypoetry/virtualenvs

Using virtualenv: /home/linuxuser/.cache/pypoetry/virtualenvs/flask-app-vnQ3DaWl-py3.12

2. Get the Activation Command

$ poetry env activate

source /home/linuxuser/.cache/pypoetry/virtualenvs/flask-app-vnQ3DaWl-py3.12/bin/activate

3. Activate the Virtual Environment

$ source /home/linuxuser/.cache/pypoetry/virtualenvs/flask-app-vnQ3DaWl-py3.12/bin/activate

Once activated, your terminal prompt will look like this:

(flask-app-py3.12) linuxuser@:~/flask-app$

4. Install Flask in the Project

$ poetry add flask

This command performs several actions:

• Installs Flask and all related packages into the virtual environment.
• Records the version in your pyproject.toml file.
• Creates a poetry.lock file to lock versions for reproducibility.

Using version ^3.1.0 for flask

Updating dependencies

Resolving dependencies... (0.2s)

Writing lock file

5. Exit the Virtual Environment

$ deactivate

Configuring Firewall Rules for Flask on Ubuntu 24.04

On most Ubuntu 24.04 systems, the Uncomplicated Firewall (UFW) is enabled by default. To ensure access to your Flask app, you need to open the port it uses—typically port 5000. Use the steps below to allow traffic through port 5000 and reload the firewall settings.

1. Permit Traffic on Port 5000

$ sudo ufw allow 5000/tcp

2. Apply the Updated Firewall Configuration

$ sudo ufw reload

3. Confirm UFW Rule Activation

$ sudo ufw status

The output will typically include:

Status: active

5000/tcp (v6) ALLOW Anywhere (v6)

Running a Flask Application with Poetry

Poetry does more than just manage dependencies; it can also handle running Python projects within its managed virtual environment. Follow the instructions below to activate the virtual environment and run your Flask app.

1. Retrieve the Virtual Environment Activation Command

$ poetry env activate

The result will look like:

source /home/linuxuser/.cache/pypoetry/virtualenvs/flask-app-vnQ3DaWl-py3.12/bin/activate

2. Enable the Virtual Environment

$ source /home/linuxuser/.cache/pypoetry/virtualenvs/flask-app-vnQ3DaWl-py3.12/bin/activate

3. Change to the Flask Project Directory

$ cd flask_app

4. Create the app.py File

$ nano app.py

5. Add This Code to the File

from flask import Flask

app = Flask(__name__)

@app.route('/')
def home():
    return "<h1>Greetings</h1>"

if __name__ == '__main__':
    app.run(host='0.0.0.0', port='5000')

To save the file, press Ctrl+X, then hit Y and Enter.

This code launches a simple webpage that displays “Greetings” at the root URL.

6. Launch the Flask App with Poetry

$ poetry run python app.py

Your terminal should show an output like the following:

To view your Flask web application, open a browser and visit:

http://<SERVER-IP>:5000

To shut down the server, press Ctrl+C in your terminal.

Managing Development and Production Dependencies with Poetry

Poetry supports grouping dependencies, which helps separate development tools from production packages. Here’s how to create a development group and add pytest for testing purposes.

1. Install Pytest in a Dev Dependency Group

$ poetry add pytest --group dev

This command adds a section named [tool.poetry.group.dev.dependencies] in the pyproject.toml file. It includes pytest = "^8.3.4" as part of the dev group.

Dependencies meant for production should not belong to any group. Instead, they should go into the main section [tool.poetry.dependencies]. This ensures they are available during packaging and deployment, without being left out.

2. Create a Unit Test for the Flask App

Navigate to the testing folder within your Flask project:

$ cd ~/flask-app/tests

Create a new folder named unit:

$ mkdir unit

Move into the newly created directory:

$ cd unit

Create an __init__.py file to indicate the folder is a Python package:

$ touch __init__.py

The __init__.py file allows Python to treat the directory as a package, enabling module imports. See the official Python documentation for more details.

Create a test file named test_app.py:

$ nano test_app.py

Insert the following test code:

import pytest
from flask_app.app import app

@pytest.fixture
def client():
    with app.test_client() as client:
        yield client

def test_the_home_route(client):
    response = client.get('/')
    assert response.status_code == 200
    assert b"<h1>Greetings</h1>" in response.data

Save and close the file by pressing Ctrl+X, then Y, and finally Enter.

This unit test checks whether the Flask app’s root endpoint returns the expected HTML content.

3. Run the Unit Test

$ pytest

The output will resemble:

platform linux -- Python 3.12.3, pytest-8.3.4, pluggy-1.5.0

============================= 1 passed in 0.11s ==============================

Setting Up Gunicorn for Flask in Production

Gunicorn is a production-ready WSGI server for Python web apps. It efficiently handles multiple client requests, making it ideal for running Flask in a live environment. Below are steps to install and use Gunicorn with your Flask project.

1. Move to the Flask Application Directory

$ cd ~/flask-app/flask_app

2. Add Gunicorn as a Root Dependency

$ poetry add gunicorn

3. Create the wsgi.py File

$ nano wsgi.py

Paste the following Python code:

from app import app

if __name__ == '__main__':
    app.run()

Save and exit using Ctrl+X, then press Y and Enter.

4. Launch Flask App Using Gunicorn

$ gunicorn --bind 0.0.0.0:5000 wsgi:app

Check your web browser at:

http://<SERVER-IP>:5000

To stop the running server, use Ctrl+C in the terminal.

Managing and Recreating Poetry Virtual Environments

Poetry creates virtual environments that use up storage space, but they can be deleted and recreated as needed. Below are the steps to remove the current virtual environment and regenerate it.

1. Exit the Current Virtual Environment

$ deactivate

2. List All Virtual Environments for the Project

$ poetry env list

The currently active environment will be marked with (Activated).

flask-app-vnQ3DaWl-py3.12 (Activated)

3. Remove the Virtual Environment

$ poetry env remove flask-app-vnQ3DaWl-py3.12

Deleted virtualenv: /home/linuxuser/.cache/pypoetry/virtualenvs/flask-app-vnQ3DaWl-py3.12

4. Recreate the Virtual Environment

$ poetry env use python3

5. Retrieve the Activation Command

$ poetry env activate

source /home/linuxuser/.cache/pypoetry/virtualenvs/flask-app-vnQ3DaWl-py3.12/bin/activate

6. Activate the Virtual Environment

$ source /home/linuxuser/.cache/pypoetry/virtualenvs/flask-app-vnQ3DaWl-py3.12/bin/activate

7. Install Dependencies from pyproject.toml

$ poetry install

As long as the pyproject.toml file is intact, Poetry can restore the environment and its dependencies at any time.

Changing the Location of the Poetry Virtual Environment

By default, Poetry saves virtual environments in ~/.cache/pypoetry/virtualenvs. To better organize your project, you can place the environment directly inside the project folder.

1. Exit the Current Environment

$ deactivate

2. List Current Virtual Environments

$ poetry env list

flask-app-vnQ3DaWl-py3.12 (Activated)

3. Delete the Virtual Environment

$ poetry env remove flask-app-vnQ3DaWl-py3.12

4. Change the Environment Location Setting

$ poetry config virtualenvs.in-project true

This command overrides the default Poetry setting, placing the virtual environment inside your project’s root folder.

5. Confirm the Configuration

$ poetry config virtualenvs.in-project

true

6. Generate a New Virtual Environment

$ poetry env use python3

Creating virtualenv flask-app in /home/linuxuser/flask-app/.venv

Using virtualenv: /home/linuxuser/flask-app/.venv

7. Retrieve the Activation Command

$ poetry env activate

source /home/linuxuser/flask-app/.venv/bin/activate

8. Activate the Environment

$ source /home/linuxuser/flask-app/.venv/bin/activate

9. Display Environment Information

$ poetry env info

10. Reinstall All Project Dependencies

$ poetry install

11. Start Flask Using Gunicorn in the New Environment

$ gunicorn --bind 0.0.0.0:5000 wsgi:app

Check the application by navigating to:

http://<SERVER-IP>:5000

Conclusion

In this guide, you learned how to install and use Poetry on Ubuntu 24.04 for managing dependencies in a Flask project. You created a Poetry project, set up virtual environments, ran tests, and configured a production-ready server using Gunicorn. Additionally, you explored how to control the location and management of your virtual environments, ensuring an efficient development workflow.

For more detailed information, visit the official Poetry documentation.