Skip to content

Improve local setup documentation #67247

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
SkanderD1999 wants to merge 1 commit into
base: main
Choose a base branch
from
+7 −4
Open

Improve local setup documentation #67247

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions INSTALLING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@ This section outlines a recommended approach for setting up a local development

> ⚠️ Avoid using either system-installed Python or Python from Homebrew, as these versions are often labeled `--externally-managed` resulting in restricted dependency installation.

You can use other ways to install Python and airflow. Airflow development setup requires `uv` and if you want to setup environment for development, `uv` is the only supported local development environment setup, because we are using `uv workspace` extensively. See [local virtualenv setup in contributing docs](https://github.com/apache/airflow/blob/main/contributing-docs/07_local_virtualenv.rst) for details.
You can use other ways to install Python and Airflow. The Airflow development setup requires `uv`. If you want to set up a development environment, `uv` is the only supported local development environment setup because Airflow uses `uv workspace` extensively. See [local virtualenv setup in contributing docs](https://github.com/apache/airflow/blob/main/contributing-docs/07_local_virtualenv.rst) for details.

If you are just installing airflow to run it locally, You can use other ways to set up your Python and virtualenv: `uv` is one of the options (refer to `uv` documentation), but you can also use more traditional tools - for example `pyenv`. Note that it is recommended to install airflow with constraints - at least initially - because this way you can reproducibly install airflow. See [Installation from PyPI](https://airflow.apache.org/docs/apache-airflow/stable/installation/installing-from-pypi.html) for more details.
If you are just installing Airflow to run it locally, you can use other ways to set up your Python and virtual environment: `uv` is one option (refer to the `uv` documentation), but you can also use more traditional tools, such as `pyenv`. Note that installing Airflow with constraints is recommended, at least initially, because it makes the installation reproducible. See [Installation from PyPI](https://airflow.apache.org/docs/apache-airflow/stable/installation/installing-from-pypi.html) for more details.

### ✅ Setup using pyenv:

Expand Down Expand Up @@ -70,7 +70,7 @@ source airflow_venv/bin/activate
pip install apache-airflow==3.0.0 --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.0.0/constraints-3.11.txt"
```

Note that installing with constraints - at least initially - is recommended for reproducible installation. It might sometimes happen that 3rd-party distributions are released and their latest versions break airflow. Using constraints makes the installation reproducible with versions of dependencies that were "frozen" at the time of releasing airflow. Note you have to specify both - airflow version and Python version you are using.
Note that installing with constraints - at least initially - is recommended for reproducible installation. It might sometimes happen that 3rd-party distributions are released and their latest versions break airflow. Using constraints makes the installation reproducible with versions of dependencies that were "frozen" at the time of releasing airflow. Note you have to specify both - Airflow version and Python version you are using.

You can also specify additional extras - when you want to install airflow with additional providers:

Expand All @@ -86,7 +86,9 @@ pip install apache-airflow[amazon,google]==3.0.0 --constraint "https://raw.githu
export AIRFLOW_HOME=~/airflow
```

7. **Run Airflow in standalone mode**: Apache Airflow runs several components, like the scheduler, web server, and API server, to manage workflows and show the UI.
> **Note:** This command sets `AIRFLOW_HOME` for the current shell session only. To make it persistent, add the line to your shell profile, such as `~/.bashrc` or `~/.zshrc`.

7. **Run Airflow in standalone mode**: Apache Airflow runs several components, such as the scheduler, web server, triggerer, and API server, to manage workflows and display the UI.

- To run Airflow in standalone mode (which will automatically start the required components):

Expand All @@ -101,3 +103,4 @@ airflow standalone
```text
http://localhost:8080
```
**Note:** The `airflow standalone` command prints the generated username and password in the terminal on first run. Use these credentials to log in to the Airflow UI.