POC airflowctl Binary

[fritz-astronomer]

No description provided.

[bugraoz93]

You should be able to find an executable version when you install it in your environment from pip. For sure, it is not a binary but should be totally executable in all environments that can execute Python, which abstracts the execution binary, assuming independence of OS version.

#!/<path_to_env>/apache-airflow-ctl/bin/python
# -*- coding: utf-8 -*-
import re
import sys
from airflowctl.__main__ import main
if __name__ == '__main__':
    sys.argv[0] = re.sub(r'(-script\.pyw|\.exe)?$', '', sys.argv[0])
    sys.exit(main())

<path_to_env>/bin/airflowctl
Maybe I am missing some context

[fritz-astronomer]

ah, that's cool @bugraoz93 .
I was specifically considering if there'd be a way to have a dependency-less Airflow client or worker running somewhere.
Looks like there is :) with pyinstaller

Wasn't initially intending to PR to the main airflow project, I had misclicked. Just wanted to save the idea as a POC

[potiuk]

I was specifically considering if there'd be a way to have a dependency-less Airflow client or worker running somewhere.

What's wrong with uv tool install apache-airflow-ctl ? @fritz-astronomer :D ?

[fritz-astronomer]

@potiuk - nothing wrong with that, was just considering a scenario like "what about on an old machine without python / uv / etc".
I forgot that running tasks is in main airflow CLI, though, not airflowctl, which limits the effectiveness but this is still an interesting POC, IMO

[potiuk]

@potiuk - nothing wrong with that, was just considering a scenario like "what about on an old machine without python / uv / etc". I forgot that running tasks is in main airflow CLI, though, not airflowctl, which limits the effectiveness but this is still an interesting POC, IMO
o
I think uv is generally working anywhere and has way better coverage of supported systems that pyinstaller can do.

Installing uv is super easy, and I think people still have misconception about how difficult it is to run a modern version of python application/cli on virtually any system. The main premise of uv tool is that it just works. And you don't think that about python version, venv, installing package - or even that it's a python app.

I honstly think that publishing your CLI package to PyPI and asking your users - if you want to easily install things then go:

curl -LsSf https://astral.sh/uv/install.sh | sh

(or whatever your OS needs from https://docs.astral.sh/uv/getting-started/installation/)

followed by

uv tool install YOUR_PACKAGE

Of course - that should also be paired with regular pip install installation or maybe pipx install - for those who manage their own Python and are more "experienced".

But adding pyinstaller and stuff to the mix only complicates things and does not - eventually - make it easier even for casual non-python-profficient users.

[fritz-astronomer]

@potiuk - having just one downloadable file, in my experience from building a few other utilities, is definitely helpful for a specific subset of user (often a less technical user, potentially on an outdated OS, and/or on a heavily restricted environment where they don't have permissions to install things to their workstations).

Though, to be clear, I do think that's a minority of users.
I am not advocating a massive investment, just for those edge-case unhappy-path user scenarios.

I don't want to imply that this POC was intended to be "I think this should be the main way folks run Airflow". This POC was just me considering ways to unblock certain scenarios - like running Airflow on a heavily locked-down machine/workstation (maybe one that can't install uv, but could run a binary that gets scpd to the machine)

You are very correct - uv is a wonderful tool and I use it all the time.
uv tool install apache-airflow-ctl is definitely a great way to encourage the happy-path of folks to proceed :)

---

You did peak my curiosity, @potiuk . With uv, I wonder if that'd make the extremely-unhappy-path (e.g. a locked-down windows workstation, without python or only an extremely out-of-date python) meaningfully easier for running Airflow - either the command-line or a worker.
I do know uv can install newer/correct versions of python.
I'll give it a shot, while I'm exploring the idea

[potiuk]

without python or only an extremely out-of-date python

Unlikely :) . If you have extremely old version of Python, airflowctl itself won't work

locked-down windows workstation

1. mkdir tmp; cd tmp
2. pip download apache airflow-ctl
3. cp *.whl your_usb

on locked workstation:

4. cp your_usb/* .
5. pip install *

And yes I know it's not as easy as one binary, but still can work

[fritz-astronomer]

uv does download an up-to-date python for you without a fuss 👍
So that'd help if the hypothetical user could at least do that.

uv did make it really easy to run airflowctl on a brand-new windows VM without python or anything else, in only three commands:

C:\Users\Fritz>powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"    
C:\Users\Fritz>uv tool install apache-airflow-ctl
C:\Users\Fritz>airflowctl

Though, we'll ignore for the moment that argparse appears to blow up on either windows, generally, or py3.14.
I'm sure there's other airflow-on-windows incompatibilities, to deal with - but that's not the specific point of this thought-thread

C:\Users\Fritz>airflowctl
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "C:\Users\Fritz\.local\bin\airflowctl.exe\__main__.py", line 10, in <module>
    sys.exit(main())
             ~~~~^^
  File "C:\Users\Fritz\AppData\Roaming\uv\tools\apache-airflow-ctl\Lib\site-packages\airflowctl\ctl\cli_parser.py", line 161, in _add_action_command
    arg.add_to_parser(sub_proc)
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^
  File "C:\Users\Fritz\AppData\Roaming\uv\tools\apache-airflow-ctl\Lib\site-packages\airflowctl\ctl\cli_config.py", line 155, in add_to_parser
    parser.add_argument(*self.flags, **self.kwargs)
    ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\Fritz\AppData\Roaming\uv\python\cpython-3.14.0-windows-x86_64-none\Lib\argparse.py", line 1538, in add_argument
    action = action_class(**kwargs)
TypeError: BooleanOptionalAction.__init__() got an unexpected keyword argument 'type'

I don't think pyinstaller would provide anything better, here.
It bundles python and all the deps into the .exe, but I don't think that fixes any windows-specific incompatibilities.

[potiuk]

I think the reason might be general 3.14 non-compatibility. Try it with uv install apache-airfllow-ctl --python 3.13 @fritz-astronomer

cc: @bugraoz93 -> I think that there is a problem with airflow-ctl and Python 3.14 (FYI @fritz-astronomer -> Airflow code i n general is not Python 3.14 tested including airflowctl) Requires-Python: >=3.10 and probably we should explicitly change it to !=3.14 - until at least we attempt to add 3.14 to supported versions./

[bugraoz93]

I think the reason might be general 3.14 non-compatibility. Try it with uv install apache-airfllow-ctl --python 3.13 @fritz-astronomer

cc: @bugraoz93 -> I think that there is a problem with airflow-ctl and Python 3.14 (FYI @fritz-astronomer -> Airflow code i n general is not Python 3.14 tested including airflowctl) Requires-Python: >=3.10 and probably we should explicitly change it to !=3.14 - until at least we attempt to add 3.14 to supported versions./

Great finding indeed! Thanks @fritz-astronomer!

@potiuk Let's ensure it is documented and clearly stated for installation. Would it be okay to release in the next RC? I have small work on CI, so in the following days, I hope will raise the PR and we can prepare for the next release!

#58653

[potiuk]

@potiuk Let's ensure it is documented and clearly stated for installation. Would it be okay to release in the next RC? I have small work on CI, so in the following days, I hope will raise the PR and we can prepare for the next release!

Yeah. No need to fix it now. - but I noticed we have generally some inconsistencies that I want to address in main so I will fx it constistently for all distributions that need it.

[potiuk]

PR here #58657