Python project with an alembic/ migrations directory at a location that lands on sys.path (e.g. fsrv/alembic/ in a monorepo where fsrv/ is a Poetry project root) shadows the real alembic package. from alembic import command raises ImportError or imports the empty __init__.py from the local directory instead. Happens with any poetry run invocation, pytest, or python -c when the project root is on sys.path. The alembic/ directory has an __init__.py (required for Alembic's own imports of env.py), which makes Python treat it as a package that wins over the installed alembic.
Rename the migrations directory from alembic/ to migrations/ (or any non-colliding name). Update script_location in alembic.ini to point to the new path. Then grep the entire repo for references — common locations: CI volume mounts, pre-commit hook file patterns, test fixture discovery paths (relative ../../alembic/tests), schema CLI tooling, and shell scripts that reference the versions directory. The alembic.ini file itself does NOT need renaming — it's a file, not a package directory, so it doesn't shadow anything. This is a one-time, zero-runtime-cost fix. Typical files to update: alembic.ini (script_location), any CI workflow volume mounts, pre-commit config file patterns, shell scripts referencing the versions dir, test utilities with relative path traversal to the migrations/tests dirs, and any mirror/sync scripts that detect migration file changes via git diff paths.