Apache Airflow version

main (development)

If "Other Airflow 3 version" selected, which one?

No response

What happened?

Description:
I am encountering a persistent version check error when running breeze start-airflow. Even though prek is clearly updated to version 0.3.3 within the Breeze tool environment (as verified by pip list), Breeze continues to report that it finds version 0.2.25 and fails to start.

Environment:

• OS: macOS
• Docker Version: 29.1.3
• Docker Compose Version: 2.40.3
• Host Python: 3.11.14 (Clang 21.1.4)
• Breeze Installation: Installed via uv tool

Steps to Reproduce:

1. Install/Update Breeze using uv tool install apache-airflow-breeze.
2. Run the following command:

   breeze start-airflow --executor CeleryExecutor --python 3.11 --backend mysql

3. Observe the version mismatch error despite manual verification.

Actual Logs & Evidence:

The error message indicates it is checking the specific path /Users/uplsh/.local/share/uv/tools/apache-airflow-breeze/bin/python:

$ breeze start-airflow --executor CeleryExecutor --python 3.11 --backend mysql
Docker container engine detected.
Good version of Docker: 29.1.3.
Good version of docker-compose: 2.40.3
Host python version is 3.11.14 (main, Dec 17 2025, 21:09:14) [Clang 21.1.4 ]
Checking prek installed for /Users/uplsh/.local/share/uv/tools/apache-airflow-breeze/bin/python

Package name prek version is wrong. It should be at least 0.3.2 and is 0.2.25.

However, checking the version using the exact same python binary shows that 0.3.3 is already installed:

$ /Users/uplsh/.local/share/uv/tools/apache-airflow-breeze/bin/python -m pip list | grep prek
prek                      0.3.3

$ /Users/uplsh/.local/share/uv/tools/apache-airflow-breeze/bin/python --version
Python 3.11.14

Additional Context:
I have tried the following to resolve the issue, but none worked:

• uv tool install --force --refresh --upgrade apache-airflow-breeze
• rm -rf /Users/uplsh/.local/share/uv/tools/apache-airflow-breeze followed by a fresh install.
• Manually running pip install --upgrade prek for the tool's python binary.

It seems like the prek version check logic in Breeze might be hitting a stale cache or checking a different metadata location than what pip reports.

What you think should happen instead?

Root Cause Analysis

Issue: assert_prek_installed logic in Breeze displays the python_executable path in its error message, but it actually validates the version by calling prek --version from the system PATH instead of the Python environment's site-packages.

The Mismatch:

• PATH prek: 0.2.25 (This is what Breeze actually checks)
• Breeze Python prek: 0.3.3 (This is what pip list shows, but Breeze ignores this)

How to reproduce

1. Install an older version of prek globally via uv: This ensures that the prek command in your system PATH is outdated.

uv tool install prek==0.2.25 --force

2. Install the latest version of prek inside the Breeze tool's specific Python environment: This creates the situation where the environment's package is actually up-to-date, but the PATH version is not.

YOUR_PATH/uv/tools/apache-airflow-breeze/bin/python -m pip install "prek>=0.3.3"

3. Verify the version mismatch: Confirm that the two locations are pointing to different versions.

# Check system PATH version
prek --version 
# Should return: 0.2.25

# Check Breeze's internal Python environment version
YOUR_PATH/uv/tools/apache-airflow-breeze/bin/python -m pip list | grep prek 
# Should return: 0.3.3

4. Run Breeze to trigger the error: Breeze will report a version error for the Python path, even though the actual check is failing due to the version in the system PATH.

breeze start-airflow

Operating System

MacOS Tahoe 26.3

Versions of Apache Airflow Providers

No response

Deployment

Official Apache Airflow Helm Chart

Deployment details

Short-term Workaround (On Your env)

Upgrade system prek version

# Upgrade prek in the tool path
uv tool upgrade prek

# OR Force reinstall
uv tool install prek --force

Long-term Solution (Airflow Project)

I suggest improving the assert_prek_installed function in the Breeze project as follows:

Ensure Consistency in Validation Logic
The current check logic should be updated to prioritize the prek version installed within the python_executable environment displayed in the error message.

• Current: Checks prek --version via system PATH.
• Proposed: Check the version using the specific Python binary to ensure it matches the environment Breeze is actually using.
  • Method: Use python -m prek --version or importlib.metadata.

Anything else?

No response

Are you willing to submit PR?

• Yes I am willing to submit a PR!

Code of Conduct

• I agree to follow this project's Code of Conduct