You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by ra...@apache.org on 2026/10/13 11:21:38 UTC
(airflow) 01/04: Simplify the Quick Start for first-time local installs (#72754)
This is an automated email from the ASF dual-hosted git repository.
vatsrahul1001 pushed a commit to branch v3-4-test
in repository https://gitbox.apache.org/repos/asf/airflow.git
commit 3c5eacc0e248445e0b5bd268adb05effc44d4231
Author: Sruthi <sr...@gmail.com>
AuthorDate: Tue Oct 13 03:38:54 2026 -0700
Simplify the Quick Start for first-time local installs (#72754)
* Simplify the Quick Start for first-time local installs
First-time users land on a page that mixes a local standalone walkthrough with extras, stale version pins, and unsupported-tool discussion. Those details already live on the installation pages, and they make the most-visited getting-started guide hard to copy and easy to get wrong.
* Fix Quick Start and PyPI tool-install commands that fail as written
Every command on the Quick Start now runs as written against a released
Airflow in a clean environment.
`pipx run apache-airflow standalone` fails with "No such file or
directory: 'airflow'": standalone starts each component by running
`airflow` from PATH, and `pipx run` does not put it there. The pipx tab
is dropped from the Quick Start. On the PyPI page, `pipx run` and
`uv tool install` failed the same way; they now use
`pipx install --include-deps` and
`uv tool install --with-executables-from apache-airflow-core`.
The uv tab creates the environment with `--python 3.13`, so uv supplies
a supported interpreter, and the uvx shortcut pins the documented
version and its constraints file. The pip tab covers the missing
python3-venv module on Debian and Ubuntu and the 404 an unsupported
Python produces. The page shows real standalone output, says where the
password is on later runs, and replaces the `tasks test` check with
unpausing an example Dag. The components-separately steps say to use
one terminal per component.
* Keep the Quick Start to the two constraint-based install paths
The uvx shortcut skipped the constraints file the page relies on, so it
is gone, leaving the uv and pip tabs. The uv tab no longer hard-codes a
Python version; it explains `--python` instead. The page now shows the
SimpleAuthManager production warning that every standalone run prints
and says why it appears, reads the password file from `AIRFLOW_HOME`,
and quotes the error each installer gives for an unsupported Python.
The PyPI page goes back to its current content. Its `pipx run` and
`uv tool install` commands fail because standalone starts components by
running `airflow` from PATH, which is better fixed in standalone itself.
* Use a placeholder for the generated password in the Quick Start
---------
Co-authored-by: Sruthi <co...@users.noreply.github.com>
Co-authored-by: Kaxil Naik <ka...@gmail.com>
---
airflow-core/docs/installation/index.rst | 39 ++++--
airflow-core/docs/start.rst | 233 +++++++++++++------------------
2 files changed, 124 insertions(+), 148 deletions(-)
diff --git a/airflow-core/docs/installation/index.rst b/airflow-core/docs/installation/index.rst
index 87fd0b52420..e1716674160 100644
--- a/airflow-core/docs/installation/index.rst
+++ b/airflow-core/docs/installation/index.rst
@@ -52,24 +52,45 @@ also be kept updated when Airflow is upgraded.
Local start for development and testing
'''''''''''''''''''''''''''''''''''''''
-You just want to try Apache Airflow without all production complexity? If you have ``pipx`` installed,
-you can install Airflow directly from PyPI with the command below:
+To run Airflow on your machine for development and testing, follow the :doc:`/start`. It installs Airflow
+into a virtual environment and starts every component with ``airflow standalone``, which is not meant for
+production.
+
+.. _starting-components-separately:
+
+Starting components separately
+""""""""""""""""""""""""""""""
+
+The ``airflow standalone`` command starts every component for you. To run them yourself, create the database
+tables once:
.. code-block:: bash
- pipx run apache-airflow standalone
+ airflow db migrate
-Alternatively, you can do something similar with Astral ``uv``:
+Then start each component in its own terminal, with the same virtual environment activated and the same
+``AIRFLOW_HOME`` if you set one. Each command keeps running until you stop it:
.. code-block:: bash
- uvx apache-airflow standalone
+ airflow api-server --port 8080
+ airflow scheduler
+ airflow dag-processor
+ airflow triggerer
-Which starts a minimal system with an auto-generated admin password and SQLite database, so you can
-start using Airflow right away. This is a great way to get familiar with Airflow and try it out
-without the need to set up a complex environment.
+With the default ``SimpleAuthManager``, the API server prints a generated password for the ``admin`` user on
+its first start and saves it in ``simple_auth_manager_passwords.json.generated`` under ``AIRFLOW_HOME``
+(``~/airflow`` unless you set it). If you use the :doc:`apache-airflow-providers-fab:auth-manager/index`
+instead, create an admin user with ``airflow users create``, which prompts for a password:
+
+.. code-block:: bash
-Note that the standalone mode is not for production purposes. But it is a simple start for a local development.
+ airflow users create \
+ --username admin \
+ --firstname Peter \
+ --lastname Parker \
+ --role Admin \
+ --email spiderman@superhero.org
Using released sources
''''''''''''''''''''''
diff --git a/airflow-core/docs/start.rst b/airflow-core/docs/start.rst
index b8a882f75f4..f0e34be0806 100644
--- a/airflow-core/docs/start.rst
+++ b/airflow-core/docs/start.rst
@@ -16,186 +16,141 @@
under the License.
-
Quick Start
-----------
-This quick start guide will help you bootstrap an Airflow standalone instance on your local machine.
-
-.. note::
+Install Airflow on your machine and start it with ``airflow standalone``, which runs the scheduler, Dag
+processor, triggerer and API server together on a SQLite database. Use it to try Airflow and to develop
+Dags locally, not in production. For other ways to install and run Airflow, see :doc:`/installation/index`.
- Successful installation requires a Python 3 environment. Airflow supports Python 3.11, 3.12, 3.13, 3.14.
+Before you start
+''''''''''''''''
- Officially supported installation methods are ``pip`` or ``uv``.
+You need a Python version that this Airflow release supports; see :doc:`/installation/prerequisites`.
- Run ``pip install apache-airflow[EXTRAS]==AIRFLOW_VERSION --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-AIRFLOW_VERSION/constraints-PYTHON_VERSION.txt"``, for example :subst-code:`pip install "apache-airflow[celery]==|version|" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-|version|/constraints-3.11.txt"` to install Airflow in a reproducible way. You can also use - much faster - ``uv`` - by adding ``uv`` before the command.
+On Windows, set up WSL2 first: run ``wsl --install`` in PowerShell as administrator and restart, as described
+in `Install WSL <https://learn.microsoft.com/en-us/windows/wsl/install>`__. Then run every command below in
+the Ubuntu terminal that WSL2 installs.
+Install Airflow
+'''''''''''''''
+Create a virtual environment and install Airflow into it with the
+:ref:`constraints file <installation:constraints>`, which pins every dependency to the version this release
+was tested with. A later release of a dependency then does not change what you install.
- While there have been successes with using other tools like `poetry <https://python-poetry.org/>`_ or
- `pip-tools <https://pypi.org/project/pip-tools/>`_, they do not share the same workflow as
- ``pip`` or ``uv`` - especially when it comes to constraint vs. requirements management.
- Installing via ``Poetry`` or ``pip-tools`` is not currently supported.
+.. tab-set::
- If you wish to install Airflow using those tools you should use the constraint files and convert
- them to appropriate format and workflow that your tool requires.
+ .. tab-item:: uv
+ :sync: uv
- This guide will help you quickly set up Apache Airflow using ``uv``, a fast and modern tool for managing Python environments and dependencies. ``uv`` makes the installation process easy and provides a
- smooth setup experience.
+ If you do not have uv yet, install it from the
+ `uv installation guide <https://docs.astral.sh/uv/getting-started/installation/>`__. Then create the
+ virtual environment and install Airflow:
- If you are on Windows, you have to use WSL2 (Linux environment for Windows).
+ .. code-block:: bash
+ :substitutions:
- .. code-block:: bash
+ uv venv
+ source .venv/bin/activate
- wsl --install
+ AIRFLOW_VERSION=|version|
+ PYTHON_VERSION="$(python -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
+ CONSTRAINT_URL="https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt"
+ uv pip install "apache-airflow==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"
-1. **Set Airflow Home (optional)**:
+ ``uv venv`` uses a Python it finds on your machine. To choose a supported version instead, pass it
+ with ``--python``, and uv downloads it if it is missing.
- 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.
+ .. tab-item:: pip
+ :sync: pip
- .. code-block:: bash
+ On Debian and Ubuntu, including WSL2, install the ``venv`` module first with
+ ``sudo apt update && sudo apt install python3-venv``. Without it, ``python3 -m venv`` fails with
+ ``The virtual environment was not created successfully because ensurepip is not available``.
- export AIRFLOW_HOME=~/airflow
+ Then create the virtual environment and install Airflow:
-2. Install Airflow in a virtual environment using ``uv`` since it is a faster alternative that creates the ``venv`` automatically for you. It is an efficient alternative to using ``pip`` and ``venv``.
+ .. code-block:: bash
+ :substitutions:
- .. rst-class:: centered
+ python3 -m venv .venv
+ source .venv/bin/activate
+ pip install --upgrade pip
- Install uv: `uv Installation Guide <https://docs.astral.sh/uv/getting-started/installation/>`_
+ AIRFLOW_VERSION=|version|
+ PYTHON_VERSION="$(python -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
+ CONSTRAINT_URL="https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt"
+ pip install "apache-airflow==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"
+If the virtual environment's Python is a version this release does not support, no constraints file exists for
+it and the install stops at the constraints URL. pip reports ``ERROR: 404 Client Error: Not Found for url:``
+and uv reports ``error: Error while accessing remote requirements file:``, each followed by the URL. Recreate
+the virtual environment with a supported Python.
- For creating virtual environment with ``uv``, refer to the documentation here:
- `Creating and Maintaining Local virtual environment with uv <https://github.com/apache/airflow/blob/main/contributing-docs/07_local_virtualenv.rst#creating-and-maintaining-local-virtualenv-with-uv-recommended>`_
+Start Airflow
+'''''''''''''
-For installation using ``pip`` and ``venv``, carry out the following steps.
-On Debian/Ubuntu systems, Python may enforce
-externally managed environments (PEP 668), so use a virtual environment
-before running ``pip install`` commands:
+With the virtual environment activated, start every component with one command:
.. code-block:: bash
- :substitutions:
-
- # For Windows after WSL2 install, restart computer, then in WSL Ubuntu terminal
- sudo apt update
- sudo apt install python3-pip python3-venv
-
- # Go to Linux home directory (not Windows mount)
- cd ~
-
- # Create airflow directory
- mkdir -p ~/airflow
- cd ~/airflow
-
- # Create virtual environment
- python3 -m venv airflow_venv
-
- # Activate
- source airflow_venv/bin/activate
-
- # Upgrade pip
- pip install --upgrade pip
-
- # Install Airflow with correct Python version constraints
- pip install apache-airflow[celery]==|version| --constraint https://raw.githubusercontent.com/apache/airflow/constraints-|version|/constraints-3.12.txt
-
- # Verify installation
- airflow version
-
-3. Install Airflow using the constraints file, which is determined based on the URL we pass:
-
- .. code-block:: bash
- :substitutions:
-
-
- AIRFLOW_VERSION=|version|
-
- # Extract the version of Python you have installed. If you're currently using a Python version that is not supported by Airflow, you may want to set this manually.
- # See above for supported versions.
- PYTHON_VERSION="$(python -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
- CONSTRAINT_URL="https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt"
- # For example this would install |version| with python 3.11: https://raw.githubusercontent.com/apache/airflow/constraints-|version|/constraints-3.11.txt
+ airflow standalone
- uv pip install "apache-airflow==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"
+On the first run, Airflow creates ``~/airflow`` with its configuration file ``airflow.cfg`` and a SQLite
+database, and generates a password for the ``admin`` user. The password appears near the start of the
+output. Once the API server, scheduler, Dag processor and triggerer are all running, Airflow prints a ready
+banner. The components' logs fill the lines in between:
-4. Run Airflow Standalone:
+.. code-block:: text
- The ``airflow standalone`` command initializes the database, creates a user, and starts all components.
+ standalone | Starting Airflow Standalone
+ [warning ] SimpleAuthManager is active but the deployment shape looks like production (non-sqlite backend, non-local API host, or a distributed executor). ...
+ Simple auth manager | Password for user 'admin': <generated-password>
+ ...
+ standalone | Airflow is ready
+ standalone | Airflow Standalone is for development purposes only. Do not use this in production!
- .. code-block:: bash
+The ``SimpleAuthManager is active but the deployment shape looks like production`` warning is expected for a
+local standalone run: the API server listens on ``0.0.0.0`` by default, which the warning treats as a
+non-local host.
- airflow standalone
+Press ``Ctrl+C`` to stop every component.
- .. note::
+Airflow keeps its files in ``~/airflow`` unless you set ``AIRFLOW_HOME``. If you set it, export the same value
+in every terminal before you run ``airflow``: a terminal without it uses ``~/airflow``, with a separate
+database and password. To start Airflow again later, open a terminal in the directory where you created the
+virtual environment, run ``source .venv/bin/activate``, then ``airflow standalone``.
- In Airflow 3.x, the admin password may not always be displayed in the terminal output when running ``airflow standalone``.
+Log in and run a Dag
+''''''''''''''''''''
- The password is automatically generated and stored in:
-
- ``$AIRFLOW_HOME/simple_auth_manager_passwords.json.generated``
-
- To retrieve it, run:
-
- .. code-block:: bash
-
- cat ~/airflow/simple_auth_manager_passwords.json.generated
-
- Use this password to log in to the web interface instead of default credentials.
-
-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 on the home page.
-
-Upon running these commands, Airflow will create the ``$AIRFLOW_HOME`` folder
-and create the "airflow.cfg" file with defaults that will get you going fast.
-You can override defaults using environment variables, see :doc:`/configurations-ref`.
-You can inspect the file either in ``$AIRFLOW_HOME/airflow.cfg``, or through the UI in
-the ``Admin->Configuration`` menu. The PID file for the webserver will be stored
-in ``$AIRFLOW_HOME/airflow-api-server.pid`` or in ``/run/airflow/airflow-webserver.pid``
-if started by systemd.
-
-As you grow and deploy Airflow to production, you will also want to move away
-from the ``standalone`` command we use here to running the components
-separately. You can read more in :doc:`/administration-and-deployment/production-deployment`.
-
-Here are a few commands that will trigger a few task instances. You should
-be able to see the status of the jobs change in the ``example_bash_operator`` Dag as you
-run the commands below.
+Open ``http://localhost:8080`` and log in as ``admin`` with the password from the
+``Password for user 'admin'`` line. Airflow prints that line only on the first run; later runs print a line
+saying the password was previously generated, with the path of the file that holds it. To read the file:
.. code-block:: bash
- # run your first task instance
- airflow tasks test example_bash_operator runme_0 2015-01-01
- # run a backfill over 2 days
- airflow backfill create --dag-id example_bash_operator \
- --from-date 2015-01-01 \
- --to-date 2015-01-02
-
-If you want to run the individual parts of Airflow manually rather than using
-the all-in-one ``standalone`` command, you can instead run:
-
-.. code-block:: bash
-
- airflow db migrate
-
- airflow users create \
- --username admin \
- --firstname Peter \
- --lastname Parker \
- --role Admin \
- --email spiderman@superhero.org
+ cat "${AIRFLOW_HOME:-$HOME/airflow}/simple_auth_manager_passwords.json.generated"
- airflow api-server --port 8080
+It maps each user to their password:
- airflow scheduler
+.. code-block:: text
- airflow dag-processor
+ {"admin": "<generated-password>"}
- airflow triggerer
+Airflow loads a set of example Dags, all paused. Open **Dags**, find ``example_bash_operator``, and switch on
+its toggle to unpause it. The scheduler starts a run within a few seconds; click the Dag name to follow its
+tasks.
-.. note::
- ``airflow users`` command is only available when :doc:`apache-airflow-providers-fab:auth-manager/index` is enabled.
+What's next
+'''''''''''
-What's Next?
-''''''''''''
-From this point, you can head to the :doc:`/tutorial/index` section for further examples or the :doc:`/howto/index` section if you're ready to get your hands dirty.
+* :doc:`/tutorial/index` to write your first Dag
+* :doc:`/installation/installing-from-pypi` for extras, providers, and how constraints files work
+* :doc:`/configurations-ref` for the settings in ``airflow.cfg``
+* :ref:`starting-components-separately` to run the API server, scheduler, Dag processor,
+ and triggerer as separate processes
+* :doc:`/howto/docker-compose/index` or :doc:`helm-chart:index` for container and Kubernetes setups
+* :doc:`/administration-and-deployment/production-deployment` when you move beyond standalone
+* :doc:`/howto/index` for common configuration tasks