This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 0a3eb17ec33 #46316 Issue: Update start.rst (#46335)
0a3eb17ec33 is described below
commit 0a3eb17ec338ccee099e81bacabe967447aeb46a
Author: Saumil Patel <[email protected]>
AuthorDate: Thu Feb 6 01:30:44 2025 +0530
#46316 Issue: Update start.rst (#46335)
* #46316 Issue: Update start.rst
* Update start.rst
Added the link for detailed error
* Removed single ticks
---
docs/apache-airflow/start.rst | 31 ++++++++++++++++++++++++++-----
1 file changed, 26 insertions(+), 5 deletions(-)
diff --git a/docs/apache-airflow/start.rst b/docs/apache-airflow/start.rst
index ea8d624d74d..ff51325d0c8 100644
--- a/docs/apache-airflow/start.rst
+++ b/docs/apache-airflow/start.rst
@@ -24,7 +24,7 @@ This quick start guide will help you bootstrap an Airflow
standalone instance on
.. note::
- Successful installation requires a Python 3 environment. Starting with
Airflow 2.7.0, Airflow supports Python 3.9, 3.10, 3.11 and 3.12.
+ Successful installation requires a Python 3 environment. Starting with
Airflow 2.7.0, Airflow supports Python 3.9, 3.10, 3.11, and 3.12.
Only ``pip`` installation is currently officially supported.
@@ -44,7 +44,27 @@ This quick start guide will help you bootstrap an Airflow
standalone instance on
The installation of Airflow is straightforward if you follow the instructions
below. Airflow uses
constraint files to enable reproducible installation, so using ``pip`` and
constraint files is recommended.
-1. Set Airflow Home (optional):
+1. **(Recommended) Create and Activate a Virtual Environment**:
+
+ To avoid issues such as the ``externally-managed-environment`` error,
particularly on modern Linux distributions like Ubuntu 22.04+ and Debian 12+,
it is highly recommended to install Airflow inside a Python virtual
environment. This approach prevents conflicts with system-level Python packages
and ensures smooth installation.
+
+ For more details on this error, see the Python Packaging Authority's
explanation in the `PEP 668 documentation <https://peps.python.org/pep-0668/>`_.
+
+ .. code-block:: bash
+
+ # Create a virtual environment in your desired directory
+ python3 -m venv airflow_venv
+
+ # Activate the virtual environment
+ source airflow_venv/bin/activate
+
+ # Upgrade pip within the virtual environment
+ pip install --upgrade pip
+
+ # Optional: Deactivate the virtual environment when done
+ deactivate
+
+2. **Set Airflow Home (optional)**:
Airflow requires a home directory, and uses ``~/airflow`` by default, but
you can set a different location if you prefer. The ``AIRFLOW_HOME``
environment variable is used to inform Airflow of the desired location. This
step of setting the environment variable should be done before installing
Airflow so that the installation process knows where to store the necessary
files.
@@ -52,7 +72,8 @@ constraint files to enable reproducible installation, so
using ``pip`` and const
export AIRFLOW_HOME=~/airflow
-2. Install Airflow using the constraints file, which is determined based on
the URL we pass:
+
+3. Install Airflow using the constraints file, which is determined based on
the URL we pass:
.. code-block:: bash
:substitutions:
@@ -69,7 +90,7 @@ constraint files to enable reproducible installation, so
using ``pip`` and const
pip install "apache-airflow==${AIRFLOW_VERSION}" --constraint
"${CONSTRAINT_URL}"
-3. Run Airflow Standalone:
+4. Run Airflow Standalone:
The ``airflow standalone`` command initializes the database, creates a
user, and starts all components.
@@ -77,7 +98,7 @@ constraint files to enable reproducible installation, so
using ``pip`` and const
airflow standalone
-4. Access the Airflow UI:
+5. Access the Airflow UI:
Visit ``localhost:8080`` in your browser and log in with the admin account
details shown in the terminal. Enable the ``example_bash_operator`` DAG in the
home page.
