This looks like a real Prefect 3.6.12 packaging bug, not something wrong with your app code. What’s happening In Prefect 3.6.12,

prefect.workers.base

imports the backport package `importlib_metadata`:

from importlib_metadata import distributions

But on Python 3.12, that package often is not installed, because modern environments use the stdlib module

importlib.metadata

instead, and transitive deps may no longer pull in the backport. So in Docker, your resolved environment can end up missing

importlib_metadata

, even if the same

uv

project works locally. Why it can differ between local and Docker A few common reasons: - local env may already have

importlib_metadata

installed from earlier packages/tools - Docker build may be cleaner and only install exactly what the resolver selects -

uv

in a clean container can expose undeclared/transitive dependency assumptions Best fix Upgrade Prefect to a version where this was fixed. This was corrected in newer releases by switching to the stdlib import. If you can upgrade, that’s the best option: - Prefect 3.7 release notes Workaround if you must stay on 3.6.12 Explicitly install

importlib_metadata

in the image. For example:

dockerfile
RUN uv pip install "prefect==3.6.12" "importlib_metadata"

Or in your dependency file:

text
prefect==3.6.12
importlib_metadata

Quick checks inside the failing image

bash
python -c "import importlib_metadata; print(importlib_metadata)"
python -c "import prefect; print(prefect.__version__)"

If the first one fails, you’ve confirmed the issue. Recommendation Given you’re on Python 3.12, I’d recommend either: 1. Upgrade Prefect to a newer 3.x version, or 2. Pin

importlib_metadata

explicitly if you need to stay on 3.6.12 for now If you want, I can help you compare your local vs Docker

uv

resolution and suggest the smallest change to your Dockerfile or

pyproject.toml

.

That lines up with the same root cause. If

uv run prefect --version

fails inside the project env locally too, then this is even more clearly an environment-resolution issue with Prefect 3.6.12 on your Python 3.12 setup, not Docker-specific. What’s happening

uv run

creates/uses the project environment from declared dependencies only. In that clean env,

prefect==3.6.12

is present, but

importlib_metadata

is not, and Prefect 3.6.12 tries to import it during CLI startup. So this failure:

bash
uv run prefect --version

is consistent with the bug in 3.6.12. What to do Best option: upgrade Prefect If possible, move off 3.6.12 to a newer 3.x release where this import was fixed. If you need to stay on 3.6.12: add the missing dependency explicitly For example:

toml
[project]
dependencies = [
  "prefect==3.6.12",
  "importlib_metadata",
]

Then refresh the env:

bash
uv sync
uv run prefect --version

Or, if you want to test without editing

pyproject.toml

first:

bash
uv add importlib_metadata
uv run prefect --version

Why it may have seemed inconsistent before If you run

prefect

outside

uv run

, you may be hitting a different interpreter / virtualenv that already has

importlib_metadata

installed.

uv run

is a better test here because it isolates to the project-resolved environment. Useful verification commands

bash
uv run python -c "import prefect; print(prefect.__version__)"
uv run python -c "import importlib_metadata"

I’d expect: - first command may fail only when Prefect imports the affected module path - second command to fail right now with

ModuleNotFoundError

If you want, I can also help you pin the lowest safe upgraded Prefect version from 3.6.12 that avoids this bug while minimizing other changes.