Quickstart

Go from zero to Mage hero in under a minute. We’ll walk you through installing Mage and running your first pipeline. 🦸‍♀️

⛵️ Overview

We recommend using Docker to get started.

Docker is a tool that allows you to run Mage in a containerized environment: you can run Mage on any operating system that supports Docker, including Windows, Mac, and Linux. Using Docker means that you don’t have to worry about installing dependencies or configuring your environment. If you’d like to install Mage without Docker, you can use pip or conda.

If you’re familiar with Docker Compose or plan on adding or extending images (e.g. Postgres) in your project, we recommend starting from the Docker compose template. Otherwise, we recommend Docker run.

🪄 Get Mage

Docker compose template

Get started

The following is useful if you plan on customizing your image or adding additional services to a Docker network with Mage. Read more about Docker compose here.

Be sure that Docker and Git are installed and run:

Mac/Linux

git clone https://github.com/mage-ai/compose-quickstart.git mage-quickstart \
&& cd mage-quickstart \
&& cp dev.env .env && rm dev.env \
&& docker compose up

Once the server is running, open http://localhost:6789 in your browser and explore! We recommend one of our guides to for inspiration.

What’s happening?

We’re cloning our Docker Compose quickstart repo, copying dev.env to .env, which is ignored by git in our configuration (to avoid exposing secrets), then running docker compose up to start a Mage server.

Docker run

Get started

First, be sure Docker is installed. Next, create a new folder for your project, change directory into that folder, and run the following from your terminal:

Mac/Linux

docker run -it -p 6789:6789 -v $(pwd):/home/src mageai/mageai /app/run_app.sh mage start [project_name]

Once the server is running, open http://localhost:6789 in your browser and explore! We recommend one of our guides to for inspiration.

What’s happening?

We’re executing docker run, which runs a Docker container from the Mage image. additionally, we’re mounting a volume (the -v command) to persist our project files on our container. This mounts the current folder to /home/src in the mage container. We’re executing our docker image mageai/mageai and running a script to start up the container.

pip/conda

1. Install Mage

   pip

   pip install mage-ai
   

   _{If you’re installing on Linux and need help, check out this community provided video walkthrough.}
2. Create new project and launch tool

   mage start [project_name]
   
3. Open Mage

   Open http://localhost:6789 in your browser.

Kubernetes

1. Start a Kubernetes cluster locally

   Enable Kubernetes in Docker Desktop to start a Kubernetes cluster locally. Other options for starting a Kubernetes cluster locally are Kind and Minikube

2. Download and update Kubernetes config file

   First, download the Mage Kubernetes config file here. Then, replace the /path/to/mage_project in the config yaml with the path that you want to use to store your Mage projects.

3. Run Mage app in Kubernetes cluster

   Install the command line tool, kubectl, if you haven’t already. Run the command kubectl create -f kube/app.yaml to run Mage in a Kubernetes pod. You can check the pod status with command kubectl get pods -o wide. Set up port forwarding with command kubectl port-forward mage-server 6789:6789.

4. Open Mage

   Open http://localhost:6789 in your browser.

🏃‍♂️ Run your first pipeline

If you haven’t already, open a browser to http://localhost:6789. From the pipelines page, select example_pipeline and open the notebook view by selecting Edit pipeline from the left side nav.

Select the first cell by clicking it and select the “play” icon in the top right to run the cell. You’ve just ran your first Mage block & loaded data from a dataset!

Do the same for the following cells in the pipeline to transform and export the data. Congrats, you’re now a Mage ninja! 🥷

🧙🏻‍♂️ Install Mage dependencies (optional)

Mage also has the following add-on packages:

Package	Install	Description
all	mage-ai[all]	install all add-ons
azure	mage-ai[azure]	install Azure related packages
clickhouse	mage-ai[clickhouse]	use Clickhouse for data import or export
dbt	mage-ai[dbt]	install dbt packages
google-cloud-storage	mage-ai[google-cloud-storage]	use Google Cloud Storage for data import or export
hdf5	mage-ai[hdf5]	process data in HDF5 file format
mysql	mage-ai[mysql]	use MySQL for data import or export
postgres	mage-ai[postgres]	use PostgreSQL for data import or export
redshift	mage-ai[redshift]	use Redshift for data import or export
s3	mage-ai[s3]	use S3 for data import or export
snowflake	mage-ai[snowflake]	use Snowflake for data import or export
spark	mage-ai[spark]	use Spark (EMR) in your Mage pipeline
streaming	mage-ai[streaming]	use Streaming pipelines

To install these, run the following command from the Mage terminal:

pip install "mage-ai[spark]"

or add the following to your requirements.txt file:

mage-ai[spark]

read more about installing from requirements.txt here.

🧭 Journey on

Navigate to our tutorials to learn more about Mage and how to build your own pipelines or continue exploring our docs for advanced configuration and deployment options.

If you’re interested in connecting a database in Docker, check out our guide for more information.