PrefectHQ/fastmcp · critical · RuntimeError

uv is not installed. Please install it with: curl -LsSf http

Error message

uv is not installed. Please install it with: curl -LsSf https://astral.sh/uv/install.sh | sh

What it means

The UV environment manager shells out to the `uv` CLI to create/sync the project environment. If `uv` is not on PATH (`shutil.which('uv')` fails), `prepare()` raises RuntimeError with install instructions rather than failing obscurely later in a subprocess.

Source

Thrown at fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/uv.py:119

                self.python is not None,
                self.dependencies is not None,
                self.requirements is not None,
                self.project is not None,
                self.editable is not None,
            ]
        )

    async def prepare(self, output_dir: Path | None = None) -> None:
        """Prepare the Python environment using uv.

        Args:
            output_dir: Directory where the persistent uv project will be created.
                       If None, creates a temporary directory for ephemeral use.
        """

        # Check if uv is available
        if not shutil.which("uv"):
            raise RuntimeError(
                "uv is not installed. Please install it with: "
                "curl -LsSf https://astral.sh/uv/install.sh | sh"
            )

        # Only prepare environment if there are actual settings to apply
        if not self._must_run_with_uv():
            logger.debug("No environment settings configured, skipping preparation")
            return

        # Handle None case for ephemeral use
        if output_dir is None:
            import tempfile

            output_dir = Path(tempfile.mkdtemp(prefix="fastmcp-env-"))
            logger.info(f"Creating ephemeral environment in {output_dir}")
        else:
            logger.info(f"Creating persistent environment in {output_dir}")
            output_dir = Path(output_dir).resolve()

View on GitHub (pinned to 1f02114297)

Solutions

1. Install uv: `curl -LsSf https://astral.sh/uv/install.sh | sh` (or `pip install uv`).
2. Ensure the uv binary directory is on PATH for the process running FastMCP (`export PATH="$HOME/.local/bin:$PATH"`).
3. In Docker/CI, add an official uv install layer (e.g. `ghcr.io/astral-sh/uv`) before running the command.
4. Verify with `which uv` / `uv --version` in the same shell that runs the app.

Example fix

// before (Dockerfile)
RUN pip install fastmcp
CMD ["fastmcp", "run", "server.py"]
// after
RUN pip install fastmcp
RUN curl -LsSf https://astral.sh/uv/install.sh | sh
ENV PATH="/root/.local/bin:${PATH}"
CMD ["fastmcp", "run", "server.py"]

import shutil
if not shutil.which('uv'):
    raise SystemExit('uv is not installed. Install: curl -LsSf https://astral.sh/uv/install.sh | sh')

try:
    env.prepare(output_dir=dir)
except RuntimeError as e:
    if 'uv is not installed' in str(e):
        subprocess.run(['pip', 'install', 'uv'], check=True)
        env.prepare(output_dir=dir)
    else:
        raise

When it happens

Trigger: Running an `fastmcp` config workflow (e.g. `fastmcp run`/deploy with a uv environment) on a machine where uv was never installed, or where PATH does not include ~/.local/bin or the uv install location.

Common situations: Fresh CI containers/VMs, Docker images without uv, installing uv as a non-root user whose bin dir is not on PATH in the execution environment, venvs created before uv install.

Related errors

• Failed to initialize project: {e.stderr}
• The `google-genai` package is not installed. Install it with
• {feature} requires the `azure` extra. Install with: pip inst
• Task group is not initialized. Make sure to use run().
• {new_error_message}\nOriginal error: {e}

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/7872a4d1645055a1. Report an issue: GitHub.