Introduction

Migrating an existing requirements.txt file into Poetry is a common modernization step for Python projects. The goal is to preserve dependency intent while moving to Poetry-managed lock files and reproducible environments. A careful import workflow avoids version drift and duplicate dependency declarations.

Start with a Clean Poetry Project

If Poetry config does not exist yet:

poetry init --name my-project --no-interaction

If project already has pyproject.toml, confirm current dependencies first:

poetry show --tree

This helps you avoid importing duplicates blindly.

Import Requirements with poetry add

A practical approach is filtering comments and passing package specifiers to Poetry.

grep -v '^#' requirements.txt | grep -v '^$' > /tmp/req.clean
xargs poetry add < /tmp/req.clean

This works for straightforward requirement lines such as pinned versions and range specifiers.

Handle Dev Dependencies Separately

If you have requirements-dev.txt, import into Poetry dev group.

grep -v '^#' requirements-dev.txt | grep -v '^$' > /tmp/req-dev.clean
xargs poetry add --group dev < /tmp/req-dev.clean

Grouping keeps runtime and development dependencies clearly separated.

Validate and Lock

After import, create or refresh lock file and validate installs.

poetry lock
poetry install
poetry run python -c "import sys; print(sys.version)"

Then run your test suite to ensure dependency resolution still matches project behavior.

Handle Complex Requirement Lines

Some requirement files include:

• editable installs
• local paths
• VCS references
• environment markers

Poetry supports many of these, but syntax may differ from pip requirements format. For difficult lines, add dependencies manually in pyproject.toml and run poetry lock again.

For example, VCS dependency:

poetry add "git+https://github.com/org/repo.git#subdirectory=package"

Migration Workflow for Teams

For team migrations, use a branch and commit each step:

1. import runtime requirements
2. import dev requirements
3. run tests and static checks
4. remove legacy requirements files if policy allows
5. document Poetry commands in README

This incremental approach simplifies review and rollback.

Automating Import with a Scripted Workflow

For repeatability, teams often automate import and validation in a one-time migration script.

1#!/usr/bin/env bash
2set -euo pipefail
3
4REQ_FILE="requirements.txt"
5REQ_DEV_FILE="requirements-dev.txt"
6
7if [ ! -f pyproject.toml ]; then
8  poetry init --name migrated-project --no-interaction
9fi
10
11if [ -f "$REQ_FILE" ]; then
12  grep -v '^#' "$REQ_FILE" | grep -v '^$' > /tmp/req.main.clean
13  xargs poetry add < /tmp/req.main.clean
14fi
15
16if [ -f "$REQ_DEV_FILE" ]; then
17  grep -v '^#' "$REQ_DEV_FILE" | grep -v '^$' > /tmp/req.dev.clean
18  xargs poetry add --group dev < /tmp/req.dev.clean
19fi
20
21poetry lock
22poetry install

After script execution, run tests and compare dependency trees between old and new environments. If package resolution differs, tighten version constraints in pyproject.toml and lock again.

For multi-service repositories, migrate one service at a time. This keeps review scope manageable and avoids organization-wide dependency shifts in a single pull request.

Post-Migration Cleanup

After successful migration, decide whether to keep requirements.txt as an export artifact or remove it entirely. If your organization still requires it for certain deploy tools, generate it from Poetry rather than editing two dependency sources manually.

poetry export -f requirements.txt --output requirements.txt --without-hashes

One-way export keeps Poetry as source of truth and avoids dependency drift between files.

Common Pitfalls

A common pitfall is importing everything into default group, including test and lint dependencies.

Another issue is trusting that identical version specifiers always resolve to identical transitive trees. Lock file differences can still occur.

Developers also forget to update CI scripts from pip install -r to poetry install.

Finally, avoid keeping stale duplicate dependency sources long-term unless intentionally documented.

Summary

• Initialize or inspect Poetry project before importing.
• Import clean requirement lines with poetry add.
• Separate dev dependencies into explicit groups.
• Lock and test after migration to verify behavior.
• Update CI and documentation to standardize on Poetry workflows.