Poetry and uv on Falix

Poetry and uv are modern Python dependency managers. Instead of a hand-edited requirements.txt, they use a pyproject.toml for your declared dependencies and a lockfile (poetry.lock or uv.lock) that records the exact resolved versions. They're great tools — but the Python application has one rule that trips up newcomers, so it's worth knowing up front exactly how the two fit together on Falix.

The rule to know first

When you press Start, the Python app installs dependencies from requirements.txt — and only that file. It does not run poetry install or uv sync, and it does not read your pyproject.toml to install anything. If your project has a pyproject.toml (and lockfile) but no requirements.txt, the start installs nothing, and your app crashes the moment it imports a dependency:

ModuleNotFoundError: No module named 'requests'

⚠️ Heads up: A pyproject.toml full of dependencies looks complete, but the app's auto-install ignores it. On its own, it installs zero packages on start. You need one of the two paths below.

Path A — export a requirements.txt (most reliable)

Since the app installs requirements.txt, the bulletproof approach is to keep one alongside your pyproject.toml. Both tools generate it straight from your lockfile, so your pinned versions carry over exactly:

• uv: uv export --format requirements-txt > requirements.txt
• Poetry: poetry export -f requirements.txt -o requirements.txt (via Poetry's export plugin)

Run that on your own machine, commit the requirements.txt, and deploy. Every start installs the same locked versions — you get poetry/uv's resolution locally and a file the Python app knows how to install. Re-export whenever you change dependencies.

🎯 Good to know: This is also the cleanest fit for Git deploy: keep pyproject.toml, the lockfile, and the exported requirements.txt all in your repo. A pull brings the current locked set to the server, and the start installs it.

Path B — manage dependencies from the Packages page

The Packages page in your server menu understands pyproject.toml projects directly. When it reads your files it detects the project and picks the right tool automatically by which lockfile is present:

So a project with a uv.lock is managed with uv, one with a poetry.lock is managed with poetry, and the page runs that real tool to install, update, or remove packages — updating your pyproject.toml and lockfile for you. It also shows every dependency's Requested / Installed / Latest versions and flags known vulnerabilities, which makes it worth opening even when nothing is broken. Restart afterwards so your app picks up the change.

💡 Tip: The two paths combine well. Manage versions through the Packages page (or poetry/uv locally), then export a requirements.txt from the lockfile so the on-start install always has a file it can read. Belt and suspenders.

What pyproject.toml is good for either way

Even though the app doesn't install from it on start, keeping a pyproject.toml is worthwhile: it's where poetry/uv record your real dependency intent, it drives the Packages page's tool detection, and it holds your project metadata and the lockfile that makes installs reproducible. Think of requirements.txt as the deploy artifact the app consumes, and pyproject.toml + lockfile as the source of truth you and your tools edit.

Troubleshooting

• ModuleNotFoundError even though the package is in pyproject.toml — the classic trap above. The start only installs requirements.txt; export one (Path A) or install via the Packages page (Path B), then restart.
• Exported requirements are missing dev tools — exports default to your main dependencies. If a dev-only package is needed at runtime, it belongs in main dependencies, not the dev group.
• Packages page shows pip, not poetry/uv — no lockfile was found. Commit your poetry.lock / uv.lock so the page can detect the tool.
• Versions drift between restarts — your requirements.txt has loose rules; see Pinning Python requirements for exact pins.

For the tools themselves, the official docs go deep: python-poetry.org for Poetry and docs.astral.sh/uv for uv.

Next steps

• Pinning Python requirements
• Python on Falix
• Deploy your code with Git