11. Migrate from requirements.txt to pyproject.toml: 5-Step Process for Flask Applications

Legacy requirements.txt files lack lockfiles, leading to inconsistent installs across environments. Modern pyproject.toml (PEP 518/621) with tools like Poetry provides declarative dependencies, lockfiles (poetry.lock), and reproducible builds—ideal for Flask web apps in production.

This 5-step process migrates your Flask project seamlessly, tested on Python 3.12+ with Flask 3.0.

Why Migrate for Flask Apps?

• Reproducibility: poetry.lock pins exact versions, preventing “works on my machine” issues.
• Speed: Faster poetry install vs pip install -r requirements.txt.
• Standards: Aligns with Python’s future; supports scripts, plugins, build reqs.
• Flask Benefits: Handles dev/prod deps (e.g., flask[async]), Gunicorn, etc.

Prerequisites

• Python 3.11+
• Existing Flask app with requirements.txt
• Backup your project

Step 1: Install Poetry

curl -sSL https://install.python-poetry.org | python3 -
# Add to PATH: echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.zshrc
poetry --version

Step 2: Initialize Poetry in Your Flask Project

cd /path/to/your/flask-app
poetry init --no-interaction  # Skips interactive prompts

This creates basic pyproject.toml. Edit to set:

[tool.poetry]
name = "my-flask-app"
version = "0.1.0"
description = "Flask web application"
authors = ["Your Name <email@example.com>"]
packages = [{include = "app"}]  # Adjust to your src layout

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Step 3: Import Dependencies from requirements.txt

# Add all from requirements.txt (Poetry parses pins)
poetry add $(cat requirements.txt | sed 's/==/ /;s/>=/ /;s/<=/ /' | xargs)

# Example: requirements.txt has Flask==3.0.0 gunicorn>=21.0
# Becomes: poetry add flask==3.0.0 gunicorn>=21.0

Review pyproject.toml:

[tool.poetry.dependencies]
python = "^3.12"
flask = "^3.0.0"
gunicorn = ">=21.0"

Separate dev deps:

poetry add --group dev pytest black

Step 4: Generate Lockfile and Test Flask App

poetry lock  # Creates poetry.lock
poetry install  # Installs to .venv

# Test Flask
poetry run flask run
# Or: poetry run gunicorn app:app

Verify: App starts, endpoints work. No import errors.

Step 5: Update Scripts, CI/CD, and Cleanup

• Update run.sh or Makefile: poetry run flask run
• Docker: poetry export -f requirements.txt --output requirements.txt for prod if needed.
• GitHub Actions:

  - name: Install Poetry
    uses: snok/install-poetry@master
  - run: poetry install --no-dev

• Remove requirements.txt: git rm requirements.txt
• Commit: git add pyproject.toml poetry.lock

Common Issues & Fixes

Issue	Fix
Version conflicts	poetry lock --no-update
Extras (e.g., flask[async])	poetry add "flask[async]"
Editable installs	poetry add -e .
Monorepo	Use [tool.poetry.group.workspace.dependencies]

Verify Migration

poetry show --tree  # Dependency tree
poetry check        # Validate pyproject.toml

Conclusion

Your Flask app now uses modern pyproject.toml for reliable deploys. Next: Explore Poetry scripts for tasks.

Related:

• Poetry Docs
• PEP 621
• 10. asdf reshim errors

Share your migration experience below!