Generating a Reproducible requirements.txt with Poetry Export for CI Pipelines

Desired Outcome

Produce a requirements.txt that mirrors the exact dependency set recorded in poetry.lock. The file should be suitable for pip install -r requirements.txt in a CI job, ensuring that the CI environment installs the same package versions that Poetry resolves locally.

Prerequisites

• Poetry 1.2 or newer installed globally or per‑project (check with poetry --version).
• A valid pyproject.toml and an up‑to‑date poetry.lock in the repository root.
• Python 3.8+ in the target CI environment (the same major/minor version as used locally is recommended).
• Write permission to create or overwrite requirements.txt in the repository.

Focused Procedure

1. Open a terminal and cd to the project root where pyproject.toml lives.
2. Run the export command:

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

   Explanation of flags:

   • --without-hashes removes the hash checks that Poetry adds by default, making the file compatible with pip install -r without requiring --hash support.
   • -f requirements.txt forces the output format to a plain requirements.txt file.
   • Redirecting to requirements.txt writes the result to disk. If you prefer to keep the output on stdout, omit the redirection.
3. Commit the generated file to version control or reference it directly in your CI configuration (e.g., pip install -r requirements.txt).

Expected Checks

1. File existence: Verify that requirements.txt exists and is non‑empty.

   test -s requirements.txt && echo "File OK" || echo "Missing or empty"
   

2. Reproducibility test: In a fresh virtual environment run:

   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   pip list --format=freeze > installed.txt
   

   Then compare installed.txt with the output of poetry show --tree --format=freeze to ensure identical package names and versions.
3. Dependency tree match: Run

   poetry show --tree
   

   and confirm that every top‑level dependency listed there appears in requirements.txt with the exact version string.

Recovery Options

• Missing lock file: If the export fails with “No lock file found”, generate one with poetry lock and retry.
• Hash requirement: If your CI environment requires hash‑checking, remove --without-hashes and keep the default hash lines. Ensure the CI runner supports --hash syntax.
• Unexpected packages: If requirements.txt contains packages you did not intend (e.g., optional extras), add the --without-optional flag or explicitly exclude extras in pyproject.toml. Re‑export after adjustments.
• Version mismatch: If pip install pulls a different version, verify that the poetry.lock file is up‑to‑date. Run poetry lock --no-update to regenerate only the lock file without altering the lock state.

Limitations & Practical Verification

• Poetry’s export format changed in 1.3. Using an older Poetry version may not support --without-hashes. Always confirm poetry --version.
• Exporting with --dev will include development dependencies. Omit this flag for production CI builds.
• Transitive dependencies may be renamed or re‑resolved by Poetry during export (e.g., typing‑extensions vs typing‑extensions==4.5.0). Cross‑check against poetry.lock for intended versions.
• The exported file does not include environment markers for optional features. If your project relies on them, review the markers manually.

To verify reproducibility in production, store a checksum of the generated requirements.txt in your CI artifacts and compare it against future exports. A mismatch indicates a change in the lock file or Poetry version and warrants investigation.