Airflow cli response times

[static-moonlight]

The Airflow cli feels really slow. Is it normal that even the airflow command to print the help, takes a lot of time? Is there a way to speed that up?

$ time airflow -h
[...]
real    0m8.119s
user    0m7.744s
sys     0m0.270s

[starkmarkus]

I think the traceback shows something slightly different: it does not necessarily mean that airflow --help is already talking to the database. It looks like Airflow initializes its settings during import and tries to parse the configured sql_alchemy_conn in order to derive the async SQLAlchemy URI.

The important part seems to be this:

SQL_ALCHEMY_CONN_ASYNC = _get_async_conn_uri_from_sync(sync_uri=SQL_ALCHEMY_CONN)
...
scheme, rest = sync_uri.split(":", maxsplit=1)
ValueError: not enough values to unpack

So I would first check whether AIRFLOW__DATABASE__SQL_ALCHEMY_CONN or the corresponding airflow.cfg value is set to something invalid in that test environment. For example, an empty value, placeholder, secret name, or otherwise malformed value without a : would explain this error.

A quick check could be:

airflow config get-value database sql_alchemy_conn
env | grep AIRFLOW__DATABASE__SQL_ALCHEMY_CONN

Or, if the CLI crashes too early:

python - <<'PY'
import os
print(repr(os.environ.get("AIRFLOW__DATABASE__SQL_ALCHEMY_CONN")))
PY

For a simple local/test setup, you could also try setting it explicitly to a valid SQLite URL just to compare startup behavior:

export AIRFLOW__DATABASE__SQL_ALCHEMY_CONN='sqlite:////tmp/airflow.db'
time airflow --help

So my current guess would be:

• airflow --help does import and initialize quite a bit of Airflow, so it is not expected to be instant.
• This specific traceback is probably caused by an invalid database URI configuration, not by an actual failed database connection.
• The slow startup may still be related to the environment, filesystem, installed packages, or import overhead, but I would verify the DB URI first before drawing conclusions from this run.

[static-moonlight]

Based on your information I suspected the python environment itself and potentially the available computing resources (our test environment is not that good, but it's what I have available).

I'm using the off-the-shelf container image (docker.io/apache/airflow:3.2.2), which has a ton of providers already bundled. Roughly 30 of them, from which I might need a third or so. But since providers seems to be lazy loaded by default, and I didn't change that, I don't really think it's the providers.

As I said, our dedicated testing hardware is a bit slow, especially in the IO and networking area. On a hunch I tried to execute a simple Airflow command with no database configuration.

got ya ...

$ time airflow --help
Traceback (most recent call last):
  File "/home/airflow/.local/bin/airflow", line 3, in <module>
    from airflow.__main__ import main
  File "/home/airflow/.local/lib/python3.13/site-packages/airflow/__init__.py", line 81, in <module>
    settings.initialize()
    ~~~~~~~~~~~~~~~~~~~^^
  File "/home/airflow/.local/lib/python3.13/site-packages/airflow/settings.py", line 801, in initialize
    configure_vars()
    ~~~~~~~~~~~~~~^^
  File "/home/airflow/.local/lib/python3.13/site-packages/airflow/settings.py", line 262, in configure_vars
    SQL_ALCHEMY_CONN_ASYNC = _get_async_conn_uri_from_sync(sync_uri=SQL_ALCHEMY_CONN)
  File "/home/airflow/.local/lib/python3.13/site-packages/airflow/settings.py", line 243, in _get_async_conn_uri_from_sync
    scheme, rest = sync_uri.split(":", maxsplit=1)
    ^^^^^^^^^^^^
ValueError: not enough values to unpack (expected 2, got 1)

real    0m4.578s
user    0m4.391s
sys     0m0.145

It looks like as if the airflow CLI command is always trying to talk to the database, even for a simple --help, and starts crying when it fails :) And with slow IO in our testing environment, I think the problem might be in that direction.

It would be interesting though why Airflow is ALWAYS trying to talk to the database, even for that. For everything else it kind of makes sense, since the database seems to be used as some kind of middleware and service registry as well.

[starkmarkus]

I think the traceback shows something slightly different: it does not necessarily mean that airflow --help is already talking to the database. It looks like Airflow initializes its settings during import and tries to parse the configured sql_alchemy_conn in order to derive the async SQLAlchemy URI.

The important part seems to be this:

SQL_ALCHEMY_CONN_ASYNC = _get_async_conn_uri_from_sync(sync_uri=SQL_ALCHEMY_CONN)
...
scheme, rest = sync_uri.split(":", maxsplit=1)
ValueError: not enough values to unpack

So I would first check whether AIRFLOW__DATABASE__SQL_ALCHEMY_CONN or the corresponding airflow.cfg value is set to something invalid in that test environment. For example, an empty value, placeholder, secret name, or otherwise malformed value without a : would explain this error.

A quick check could be:

airflow config get-value database sql_alchemy_conn
env | grep AIRFLOW__DATABASE__SQL_ALCHEMY_CONN

or, if the CLI crashes too early:

python - <<'PY'
import os
print(repr(os.environ.get("AIRFLOW__DATABASE__SQL_ALCHEMY_CONN")))
PY

For a simple local/test setup, you could also try setting it explicitly to a valid SQLite URL just to compare startup behavior:

export AIRFLOW__DATABASE__SQL_ALCHEMY_CONN='sqlite:////tmp/airflow.db'
time airflow --help

So my current guess would be:

1. airflow --help does import and initialize quite a bit of Airflow, so it is not expected to be instant.
2. But this specific traceback is probably caused by an invalid database URI configuration, not by an actual failed database connection.
3. The slow startup may still be related to the environment, filesystem, installed packages, or import overhead, but I would fix/verify the DB URI first before drawing conclusions from this run.

[GayathriSrividya]

Hi everyone, I looked into this and wanted to share a structured summary since this can be confusing at first glance.

What is happening

• The traceback with ValueError: not enough values to unpack is very likely happening during startup configuration parsing, not during an actual database connection attempt.
• Airflow initializes settings early, and while deriving the async SQLAlchemy URI from the configured sync URI, a malformed value can fail fast.
• That means a slow airflow --help and an invalid sql_alchemy_conn can overlap, making the root cause look like “database is slow” when the immediate failure is actually config parsing.

What to check first

• Confirm the effective value of AIRFLOW__DATABASE__SQL_ALCHEMY_CONN in the environment where the command is executed.
• Confirm database.sql_alchemy_conn in airflow.cfg for that same runtime context.
• Look for common bad values:

1. empty string
2. placeholder text
3. secret reference string instead of a URI
4. value missing a colon separator

Quick sanity test

• Set a known-good local value temporarily (for comparison only), then rerun airflow --help.
• If the unpacking traceback disappears, that strongly indicates malformed URI config was the direct issue.

Why this still feels slow even when config is valid

• airflow --help is not a “tiny CLI only” path; startup includes non-trivial imports and initialization work.
• On constrained environments (slow disk/network/CPU, heavy image, many installed packages), this startup overhead is much more noticeable.

Follow-up fix

I opened a PR to make this failure mode explicit and actionable instead of cryptic:

#68783

What that PR does:

1. validates malformed or empty sync SQLAlchemy URI input in startup path
2. raises a clearer error message that points directly to:

• AIRFLOW__DATABASE__SQL_ALCHEMY_CONN
• sql_alchemy_conn in airflow.cfg

3. adds focused tests for:

• valid URI conversions
• malformed input behavior and messaging

If helpful, I can also share a small startup timing matrix (before/after config fix, and across two environments) to separate expected startup overhead from misconfiguration effects.

[static-moonlight]

I'm really sorry for the confusion. I deliberately "voided" the AIRFLOW__DATABASE__SQL_ALCHEMY_CONN setting before running the airflow --help command, to see if the application is touching it. I should have mentioned that before.

$ export AIRFLOW__DATABASE__SQL_ALCHEMY_CONN=""
$ time airflow --help

I falsely concluded that the error implies a database connection. But you are correct, it only means, Airflow is reading the config, nothing else.

So, I'm back to "Airflow might initializes a lot of things before it looks at what what it's actually supposed to do".

Just to have something I can compare to, can someone please run this command and tell me the time? Maybe it's normal? Maybe it's my environment? Maybe it's the container?

$ docker run --rm -it --entrypoint=bash docker.io/apache/airflow:3.2.2
airflow$ time airflow --help

[starkmarkus]

Thanks for clarifying, that makes sense. If AIRFLOW__DATABASE__SQL_ALCHEMY_CONN was deliberately set to an empty string, then the traceback is a useful sanity check that the CLI reads and parses config during startup, but it does not mean Airflow is actually attempting a database connection.

So I agree with your updated interpretation. Even for airflow --help, Airflow seems to import and initialize a fair amount before it reaches the specific CLI action, so the remaining question is how much of the observed time is normal startup and import overhead versus environment-specific overhead.

For comparison, it would be useful if people reported the exact setup together with the timing, for example:

docker run --rm -it --entrypoint=bash docker.io/apache/airflow:3.2.2
time airflow --help

and maybe also:

python -V
python -X importtime -m airflow --help 2> importtime.log

The second command might help identify whether the time is mostly Python import overhead, provider discovery, filesystem or I/O latency, or something else in the initialization path.

So I would summarize it as:

• the empty sql_alchemy_conn traceback is expected from the deliberate invalid config test
• it does not show that --help connects to the database
• but it does show that Airflow initializes configuration early
• the remaining performance question is whether 4 to 8 seconds for airflow --help is normal for the 3.2.2 container image or specific to the test environment

[GayathriSrividya]

I ran both suggested commands inside the same docker.io/apache/airflow:3.2.2 image for comparison.

Timing:

$ docker run --rm --entrypoint=bash docker.io/apache/airflow:3.2.2 -lc 'time airflow --help'

real    0m2.113s
user    0m1.751s
sys     0m0.096s

Import profiling:

$ docker run --rm docker.io/apache/airflow:3.2.2 bash -lc 'python -X importtime -m airflow --help 2> importtime.log'

Top cumulative import costs (µs):

cumulative	module
1,705,609	airflow
1,011,218	airflow.configuration
484,378	airflow.sdk.execution_time.task_runner
270,752	airflow.sdk.bases.operator
220,732	sqlalchemy
192,835	sqlalchemy.engine
142,358	libcst

Conclusion: The ~2.1s I see here is essentially all Python import and initialization overhead — airflow.configuration alone accounts for ~1s of it. So 4–8s in a slower environment is plausible purely from the same import chain running on constrained I/O or CPU. There is no actual database connection happening during --help; the traceback you saw earlier was config-parsing failing fast on the empty AIRFLOW__DATABASE__SQL_ALCHEMY_CONN you deliberately set.

[starkmarkus]

Thanks for running that comparison. That is a useful baseline.

So the picture seems to be:

clean apache/airflow:3.2.2 container on your system:
  airflow --help ≈ 2.1s
original reported environment:
  airflow --help ≈ 4-8s

and the import profile suggests the time is mostly Python import / Airflow initialization overhead, especially around:

airflow
airflow.configuration
airflow.sdk.execution_time.task_runner
airflow.sdk.bases.operator
sqlalchemy

So I think the original conclusion still holds:

• airflow --help does not appear to connect to the database
• the empty SQL_ALCHEMY_CONN traceback was config parsing, not DB connection
• airflow --help still initializes a non-trivial amount of Airflow before printing help
• 4-8s is plausible on slower CPU / disk / container storage, but slower than the clean baseline shown here

For @static-moonlight, the next useful comparison would probably be running the exact same command on the same slow test machine:

docker run --rm --entrypoint=bash docker.io/apache/airflow:3.2.2 -lc 'time airflow --help'

If that is also slow, the environment/container storage is likely the main factor. If the clean container is around 2s but the application environment is 4-8s, then the extra cost is probably coming from environment-specific config, mounts, installed packages, filesystem latency, or startup hooks.

So the practical answer to the original question seems to be: yes, airflow --help has noticeable startup/import overhead, but it should not normally be doing an actual database connection just to print help.

[GayathriSrividya]

Thanks for the clear summary, @starkmarkus . That matches what I see too.