Quick Start does not work as written on Ubuntu 24.04

[mpol]

What do you see as an issue?

When following https://airflow.apache.org/docs/apache-airflow/stable/start.html on an Ubuntu 24.04 system the pip install step fails with error: externally-managed-environment.

I would expect it to fail in the same way on a Debian Bookworm system and probably on other current distribution versions.

Solving the problem

The Debian/Ubuntu error message gives good hints how to solve the problem, but I think that a quickstart document should provide steps that work out of the box. So they should involve creating a venv, or at least, if you assume users to have some required level Python knowledge, the document should warn the user that this step may be needed.

Anything else

The full error text:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
    
    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.
    
    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.
    
    See /usr/share/doc/python3.12/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

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

[boring-cyborg]

Thanks for opening your first issue here! Be sure to follow the issue template! If you are willing to raise PR to address this issue please do so, no need to wait for approval.

[potiuk]

That is a feature of new pip relased recently. If you would like to submit a PR correcting the documentation fixing it you are most welcome (It's just a matter of clicking "suggest a change on this page" and PR will be opened for you and you can join > 3200 contributors to Airlfow and give back to the community by contributing such doc update. Other than that I mark it as "good first issue" so maybe someone will pick it up and fix. But I encourage you to make a PR.

[adan-shahid]

@potiuk Is this issue open? If yes then kindly assign it to me and guide me to start it.
Thanks!

[potiuk]

Feel free.

[Maryam3107]

What do you see as an issue?

When following https://airflow.apache.org/docs/apache-airflow/stable/start.html on an Ubuntu 24.04 system the pip install step fails with error: externally-managed-environment.

I would expect it to fail in the same way on a Debian Bookworm system and probably on other current distribution versions.

Solving the problem

The Debian/Ubuntu error message gives good hints how to solve the problem, but I think that a quickstart document should provide steps that work out of the box. So they should involve creating a venv, or at least, if you assume users to have some required level Python knowledge, the document should warn the user that this step may be needed.

Anything else

The full error text:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
    
    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.
    
    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.
    
    See /usr/share/doc/python3.12/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

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

I can solve this issue. kindly assign it to me?

[adan-shahid]

I am already working on this issue.
@Maryam3107 kindly look for another issue.