Airflow documentation updates for Windows WSL2 installation

[Srabasti]

This PR adds documentation for Airflow installation on Windows using WSL2.
Addresses closed PR: #[56566]
Airflow installation errors for grpcio #56566

---

[potiuk]

Some static checks failing

[Srabasti]

added line after ..code-block:: bash

[amoghrajesh]

The CI still fails @Srabasti:

Remove trailing whitespace at end of line........................................Failed
- hook id: trailing-whitespace
- exit code: 1
- files were modified by this hook
  Fixing airflow-core/docs/start.rst

[Srabasti]

Yes saw it failed again, sigh!!

Is there a way to see the line at which the error is happening? The above description is not helpful enough to figure out the Root Cause of the failure.

Can the static checks be enhanced to be more descriptive to include details of any errors @amoghrajesh @potiuk ?

[amoghrajesh]

@Srabasti the static check for trailing whitespaces are offloaded from the widely accepted and standard precommit checks defined in https://github.com/pre-commit/pre-commit-hooks, the errors will be clear to you if you run those hooks locally. The CI is meant to be an indicator that something is failing and it will be easily reproducible when you run it locally as well as auto fixed too.

The hook also says that it modifies the files:

Remove trailing whitespace at end of line........................................Failed
- hook id: trailing-whitespace
- exit code: 1
- files were modified by this hook
  Fixing airflow-core/docs/start.rst

The static checks are fairly simple to install and use: https://github.com/apache/airflow/blob/main/contributing-docs/08_static_code_checks.rst#using-prek and making edits from the UI for simple cases is easier but cases which have some changes like yours, would benefit better from using an IDE

[Srabasti]

There can be different ways to do the same results, however the errors from the static should still be shown in ideal scenario, so one can make out at a glance instead of troubleshooting.

As recommended, I followed the link shared above and after installing prek, was not able to use and getting error as below.

As a workaround am using precommit to fix and push the changed files to Github as follows.
Airflow_log_shared_GIT_fork_afterfixing_trailing_error_different_CLI_checks fail_airflow-fork_10262025.txt

It shows different errors now, at different points - that I have not changed at all. The original issue is fixed as not seeing that error anymore in logs above. Possibly it is due to changes in code by other developers?

[Srabasti]

Pushed changes again after running locally using "pre-commit run trailing-whitespace --files airflow-core/docs/start.rst"

[amoghrajesh]

There can be different ways to do the same results, however the errors from the static should still be shown in ideal scenario, so one can make out at a glance instead of troubleshooting.

As recommended, I followed the link shared above and after installing prek, was not able to use and getting error as below.

As a workaround am using precommit to fix and push the changed files to Github as follows. [Airflow_log_shared_GIT_fork_afterfixing_trailing_error_different_CLI_checks fail_airflow-fork_10262025.txt](https://github.com/user-attachments/files/23157665/Airflow_log_shared_GIT_fork_afterfixing_trailing_error_different_CLI_checks.fail_airflow-fork_10262025.txt)

It shows different errors now, at different points - that I have not changed at all. The original issue is fixed as not seeing that error anymore in logs above. Possibly it is due to changes in code by other developers?

After installing prek using pipx, you will have to add it to your PATH. See the note thats printed in the log about doing that, that should help your terminal detect prek (or a new terminal / respawned should help)

[Srabasti]

After installing prek using pipx, you will have to add it to your PATH. See the note thats printed in the log about doing that, that should help your terminal detect prek (or a new terminal / respawned should help)

Running "pipx ensurepath" already added the prek to the PATH, as shared above, along with the static checks passed success message. I had tried using a new terminal and relogging in however both had not worked out prior to posting message.

Today after running below, the checks got triggered again.
git commit --no-verify -m "Fix trailing whitespace in start.rst"

All checks have passed I see now. Hoping the rest goes through. Surprisingly the local checks showed more failures though here it shows all good so far!! In this scenario, prek did not work however atleast precommit did, thankfully!

[potiuk]

Suggested change

	Officially supported installation methods is with ``pip`` or ``uv``.

[potiuk]

Suggested change

Run ``pip install apache-airflow[EXTRAS]==AIRFLOW_VERSION --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-AIRFLOW_VERSION/constraints-PYTHON_VERSION.txt"``, for example ``pip install "apache-airflow[celery]==3.0.0" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.0.0/constraints-3.10.txt"`` to install Airflow in a reproducible way. You can also use - much faster - ``uv`` - by just adding ``uv`` before the command.

[potiuk]

Needs shuffling around and shortening the content.

[potiuk]

Sorry for back-forth @Srabasti , but I looked more closely and I think it's worth spending time to make things clearer that WSL2 installation is a general prerequisite if you are on Windows, but once you get it up and running - you follow a single flow - no matter if you are using Windows, Linux or Mac OS. This will also make the document shorter which will undoubtedly make @amoghrajesh happy.

[potiuk]

This is one of our most important documents for first-time contributors - this is the FIRST thing they encounter, and one that makes or breaks their "staying with the community" - so we should make sure it is as smooth and well rounded and short as possible.

[amoghrajesh]

Thanks Jarek, good call.

[Srabasti]

Thanks for your helpful review @potiuk @amoghrajesh! Lesser shuffling around for sure. Incorporated suggested changes.

[potiuk]

Still some static code changes. I think also would be good to mention both pip and uv installation as a separate step not necessarily in WSL2 section. I think the main point here is that the whole part of "install airflow" is exactly the same - no matter if you do it on Linux, MacOS or WSL2. It's just the same set of steps. So I would say WSL2 prerequisites should be decribed as separate step to do on Windows - and from then on the installation steps should be the same no matter what system you have.

[potiuk]

Also there are still some suggestions to apply for the suppports both pip and uv cases

[Srabasti]

File attached has all above changes incorporated for reshuffling content, adding uv and reverting numbering changes. airflow-forkairflowcoredocsstart.rst.txt

After making the changes and running as below, no more errors are seen - log below.
XXXX@XXXXX:/airflow/airflow-fork$ pre-commit run trailing-whitespace --files airflow-core/docs/start.rst
[WARNING] Unexpected key(s) present at root: minimum_prek_version
Remove trailing whitespace at end of line................................Passed
XXXX@XXXXX:/airflow/airflow-fork$ git add airflow-core/docs/start.rst

XXXX@XXXXX:/airflow/airflow-fork$ git add airflow-core/docs/start.rst
XXXX@XXXXX:/airflow/airflow-fork$ git config --global user.email [email protected]
XXXX@XXXXX:/airflow/airflow-fork$ git config --global user.name Srabasti
XXXX@XXXXX:/airflow/airflow-fork$ git push https://Srabasti:[email protected]/Srabasti/airflow.git Srabasti-patch-WSL2_updates
Everything up-to-date
XXXX@XXXXX:/airflow/airflow-fork$ git remote -v
origin https://github.com/Srabasti/airflow.git (fetch)
origin https://github.com/Srabasti/airflow.git (push)
XXXX@XXXXX:/airflow/airflow-fork$ git branch

• Srabasti-patch-WSL2_updates
  main
  XXXX@XXXXX:~/airflow/airflow-fork$ git status
  On branch Srabasti-patch-WSL2_updates
  Your branch is up to date with 'origin/Srabasti-patch-WSL2_updates'.

Changes to be committed:
(use "git restore --staged ..." to unstage)
modified: airflow-core/docs/start.rst

XXXX@XXXXX:/airflow/airflow-fork$ git commit --no-verify -m "Fix trailing whitespace, reshuffling content, adding uv in start.rst"
[Srabasti-patch-WSL2_updates c6cf755] Fix trailing whitespace, reshuffling content, adding uv in start.rst
1 file changed, 32 insertions(+), 37 deletions(-)
XXXX@XXXXX:/airflow/airflow-fork$ git push https://Srabasti:[email protected]/Srabasti/airflow.git Srabasti-patch-WSL2_updates
Enumerating objects: 9, done.
Counting objects: 100% (9/9), done.
Delta compression using up to 8 threads
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 803 bytes | 401.00 KiB/s, done.
Total 5 (delta 4), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
To https://github.com/Srabasti/airflow.git
f90fa3f..c6cf755 Srabasti-patch-WSL2_updates -> Srabasti-patch-WSL2_updates
XXXX@XXXXX:~/airflow/airflow-fork$ git status
On branch Srabasti-patch-WSL2_updates
Your branch is ahead of 'origin/Srabasti-patch-WSL2_updates' by 1 commit.
(use "git push" to publish your local commits)

nothing to commit, working tree clean
XXXX@XXXXX:/airflow/airflow-fork$ git push https://Srabasti:[email protected]/Srabasti/airflow.git Srabasti-patch-WSL2_updates
Everything up-to-date
srab@tania:/airflow/airflow-fork$

[potiuk]

This is now formatted as comment in .rst (it will not be visible in the rendered page).

[Srabasti]

Thanks for your inputs! Incorporated changes below.

[potiuk]

As discussed before -> the creation of the environment is the same in WSL2 and outside - so we should rather update point 2. belowInstall airflow using uv to be Install airflow in a virtual environment - and rather add explanation that uv is a faster alternative to pip and creates the venv automatically for you - but both options - with uv and withoug (just with venv + pip) should be explained there.

[Srabasti]

Thanks for your inputs! Incorporated changes below.

[Srabasti]

Carried out below rebase step with recommended changes.

-> Performed rebase by using below:
"XXXX@XXXXX:~/airflow/airflow-fork$ git config pull.rebase true"
-> Comment included for Windows WSL as applicable before Section 1, along with the steps to do so.
->Added benefits of using uv over pip and venv in Section 2, mentioning uv is recommended over pip.
->For section 2 of installation via pip and venv, moved to below instructions for uv section, with Windows in comments, so easier to follow along and both approaches under one section with no replication.
-> Removed extra lines in Section 4 and Section 5

Please advise if anything else. Thanks!