Fix uv CLI Commands Not Found in Docker

By /

Resolve ‘command not found’ for uv-Installed CLIs in Docker

The ‘command not found’ error when a Python CLI installed via uv in a Docker container is typically due to the script’s location not being on the system’s PATH environment variable. Explicitly defining a virtual environment and adding its bin directory to PATH within the Dockerfile ensures command accessibility.

The Problem

When using uv pip install within a Docker build, command-line utilities defined in pyproject.toml (e.g., [project.scripts] pypgstac = "pypgstac.pypgstac:cli") are not found by subsequent RUN commands, resulting in “pypgstac: command not found.” This occurs even though the package is successfully installed, indicating a discrepancy in how uv makes executables available within the ephemeral shell contexts of Dockerfile RUN instructions compared to a standard pip installation where the environment might be implicitly activated or PATH correctly configured.

The Solution

To ensure CLI tools installed by uv are discoverable within a Docker container, define and activate a virtual environment, then add its bin directory to the PATH environment variable.

# Dockerfile snippet illustrating the solution

# FROM python:3.10-slim-buster
# Example: Ensure uv is installed in your base image or a preceding step
# RUN pip install uv

# Define a consistent path for the virtual environment
ENV VIRTUAL_ENV=/opt/venv

# Add the virtual environment's bin directory to the PATH
# This ensures that executables installed into this venv are discoverable
ENV PATH="$VIRTUAL_ENV/bin:$PATH"

# Create the virtual environment using Python's venv module
# (uv venv --python <path_to_python> can also be used if uv is installed first)
RUN python -m venv $VIRTUAL_ENV

# Install the desired package into the created virtual environment using uv
# uv will now install pypgstac's script into $VIRTUAL_ENV/bin
RUN uv pip install pypgstac

# Verify the command-line utility is now accessible
RUN pypgstac --help

Why It Works

  • PATH Environment Variable: The operating system’s PATH variable is a list of directories where the shell looks for executable commands. If a command-line utility’s script is not located in one of these directories, the shell cannot find and execute it, leading to a “command not found” error.
  • Virtual Environments: Python virtual environments (venv) create isolated environments for Python projects, including their own bin (or Scripts on Windows) directory where installed package executables reside. For these executables to be found, this specific bin directory must be added to the system’s PATH.
  • Docker ENV and RUN Commands: Each RUN command in a Dockerfile creates a new layer. While environment variables set by ENV persist across subsequent layers, implicit PATH modifications made by certain installation tools within a single RUN command might not be automatically propagated or active in subsequent RUN commands unless explicitly exported or sourced. Setting ENV PATH ensures persistent modification across layers.
  • uv Script Installation: Like pip, uv installs package scripts into the bin directory of the active Python environment (whether it’s a virtual environment or the system environment). Explicitly setting VIRTUAL_ENV and modifying PATH ensures that uv installs into the intended location and that the system subsequently searches this location for executables.

Practical Checklist

When a CLI installed by uv is not available, check the environment before reinstalling packages. Most failures come from the command being installed in a different environment or the executable directory not being on PATH.

  • Confirm which Python environment is active.
  • Inspect the script installation directory.
  • Use absolute paths in Docker builds when reproducibility matters.

Common Mistakes

A frequent mistake is assuming the package failed to install when only the executable lookup failed. Treat package installation and shell command discovery as two separate checks.

Reference

Scroll to Top