For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
      • AstroFully-managed data operations, powered by Apache Airflow.
      • Astro Private CloudRun Airflow-as-a-service in your environment.
      • Professional ServicesExpert Airflow services for your enterprise's success.
    • Tools
      • Cosmos
      • Orbiter
      • CLI
      • AI SDK
      • Agents
      • Blueprint
      • UpdatesThe State of Airflow 2026See the insights from over 5,800 data practitioners in the full report. Download Now ➔
  • Customers
  • Docs
    • Insights
      • Blog
      • Webinars
      • Resource Library
      • Events
    • Education
      • Academy
      • What is Airflow?
  • Pricing
Get Started Free
    • Astro CLI
    • Quickstart
    • CLI reference
      • astro completion
      • astro api
      • astro auth
      • astro config
      • astro context
      • astro dbt
      • astro deploy
      • astro deployment
      • astro dev
        • astro dev bash
        • astro dev build
        • astro dev init
        • astro dev kill
        • astro dev logs
        • astro dev object export
        • astro dev object import
        • astro dev parse
        • astro dev proxy
        • astro dev ps
        • astro dev pytest
        • astro dev restart
        • astro dev run
        • astro dev start
        • astro dev stop
        • astro dev upgrade-test
      • astro ide
      • astro login
      • astro logout
      • astro organization
      • astro otto
      • astro remote
      • astro run
      • astro team
      • astro telemetry
      • astro user create
      • astro version
      • astro workspace

Product

  • Platform Overview
  • Astro
  • Astro Observe
  • Astro Private Cloud
  • Security & Trust
  • Pricing

Tools & Services

  • Cosmos
  • Docs
  • Professional Services
  • Product Updates

Use Cases

  • AI Ops
  • Data Observability
  • ETL/ELT
  • ML Ops
  • Operational Analytics
  • All Use Cases

Industries

  • Financial Services
  • Gaming
  • Retail
  • Manufacturing
  • Healthcare
  • All Industries

Resources

  • Academy
  • eBooks & Guides
  • Blog
  • Webinars
  • Events
  • The Data Flowcast Podcast
  • All Resources

Airflow

  • What is Airflow
  • Airflow on Astro
  • Airflow 3.0
  • Airflow Upgrades
  • Airflow Use Cases
  • Airflow 2.x End of Life

Company

  • Our Story
  • Customers
  • Newsroom
  • Careers
  • Contact

Support

  • Knowledge Base
  • Status
  • Contact Support
GitHubYouTubeLinkedInx
  • Legal
  • Privacy
  • Terms of Service
  • Consent Preferences

  • Do Not Sell or Share My Personal information
  • Limit the Use Of My Sensitive Personal Information

Apache Airflow®, Airflow, and the Airflow logo are trademarks of the Apache Software Foundation. Copyright © Astronomer 2026. All rights reserved.

LogoLogo
CLI referenceastro dev

astro dev init

Edit this page
Built with

The behavior and format of this command are the same for both Astro and Astro Private Cloud.

Initialize an Astro project in an empty local directory. An Astro project contains the set of files necessary to run Airflow, including dedicated folders for your dag files, plugins, and dependencies. An Astro project can be either run locally with astro dev start or pushed to Astronomer with astro deploy.

Astro
APC

Usage

1astro dev init <project-name>

Options

OptionDescriptionPossible Values
<project-name>Optional name for your Astro project. Creates and initializes a directory with the specified name.Any string
-a, --airflow-versionVersion of Airflow you want to create an Astro project with. If not specified, latest is assumed. You can change this version in your Dockerfile at any time.String (Airflow version)
-v, --runtime-versionAstro Runtime version to use for project initialization.Any supported Runtime version
-n, --nameName for your Astro project.Any string
-f, --forceInitialize the project without confirmation, even in a non-empty directory.None
--from-templateSpecify a getting started template to use as the base for your Astro project. Opens an interactive menu to select from available templates.N/A (interactive selection)
--remote-execution-enabledEnable Remote Execution mode. Prompts for remote Docker repository, generates client image files and config.N/A
--remote-image-repositoryProvide the remote image repository for client images. If omitted, prompts interactively with a warning if unset.Remote Docker image repository URI

Examples

1$ astro dev init
2# Initializes default project
3
4$ astro dev init my-airflow-project
5# Creates and initializes a directory named 'my-airflow-project'
6
7$ astro dev init --name=MyProject
8# Generates `config.yaml` file with `name=MyProject`
9
10$ astro dev init --airflow-version=2.10.5
11# Initializes project with Airflow 2.10.5
12
13$ astro dev init --airflow-version=3.1.3
14# Initializes project with Airflow 3.1.3
15
16$ astro dev init --runtime-version=13.2.0
17# Initializes project with Runtime 13.2.0
18
19$ astro dev init --runtime-version=3.1-5
20# Initializes project with Runtime 3.1-5
21
22$ astro dev init --from-template
23# Initializes project with an interactive template selection menu

Remote Execution Mode

Enabling remote execution with the --remote-execution-enabled flag results in the following behavior:

  • The CLI prompts you to provide a remote client image repository, unless you specify it with --remote-image-repository.
  • If you do not provide a repository, you receive a warning. You can also configure the remote image repository later via the astro config set remote.client_registry <remote-image-repository> CLI command
  • A new entry in .astro/config.yaml is created or updated with your remote client image repository.
  • These new files are generated for customizing dependencies and build steps for remote execution client images:
    • Dockerfile.client
    • requirements-client.txt
    • packages-client.txt

Examples

1$ astro dev init --remote-execution-enabled
2# Initialize with remote execution and prompt for repo
3
4$ astro dev init --remote-execution-enabled --remote-image-repository=images.astronomer.cloud/baseimages/astro-remote-execution-agent:3.1-4-python-3.12-astro-agent-1.2.1
5# Initialize with remote execution using vanilla Astronomer agent image
6
7$ astro dev init --remote-execution-enabled --remote-image-repository=123456789012.dkr.ecr.us-east-1.amazonaws.com/remote-execution-custom-agent:1.0.0
8# Initialize with remote execution using AWS ECR
9
10$ astro dev init --remote-execution-enabled --remote-image-repository=nexus.company.com:8083/remote-execution-custom-agent:1.0.0
11# Initialize with remote execution using Nexus registry

Related Commands

  • astro dev restart
  • astro dev run
  • astro dev logs