# Installation
If the installation instructions on the homepage or the Getting Started guide did not work on your environment, or if you'd like to learn more about how to manage your Meltano installation, you've come to the right place.
Short on time, or just curious what the fuss is about?
To get a sense of the Meltano experience in just a few minutes, follow the examples on the homepage.
They can be copy-pasted right onto your command shell and will take you all the way through
installation, data integration (EL), data transformation (T), orchestration, and containerization
with the tap-gitlab
extractor
and the target-jsonl
and target-postgres
loaders.
# Local Installation
In this section, we will install Meltano locally on your system, so that you can use it on the command line and from your browser.
# Requirements
Before you install Meltano, make sure you have the following requirements installed and up to date.
# Unix-like environment
Recent versions of Linux and macOS are both fully supported, but Windows is not.
If you'd like to run Meltano on Windows, you can install it inside the Windows Subsystem for Linux (WSL). You may also try installing Meltano on Docker, although Docker on Windows is known to have some idiosyncrasies that might hinder Meltano's ability to function.
# Python 3.6, 3.7 or 3.8
TIP
You may refer to https://realpython.com/installing-python/ for platform specific installation instructions.
Use the following command to check that you have the correct Python version installed:
python --version
# pip3
pip
is a package installer that comes automatically with Python 3+. This is also what we will be using to install Meltano. Here are some commands related to pip
that may be of interest:
# check for current version of pip to ensure that it is using Python 3
pip3 --version
# update pip3
pip3 install --upgrade pip
# Virtual Environment
IMPORTANT
Unless you are building a Docker image, it is strongly recommended that Meltano be installed inside a virtual environment in order to avoid potential system conflicts that may be difficult to debug.
Why use a virtual environment?
Your local environment may use a different version of Python or other dependencies that are difficult to manage. The virtual environment provides a "clean" space to work without these issues.
# Recommended Virtual Environment Setup
We suggest you create a directory where you want your virtual environments to be saved (e.g. .venv/
). This can be any directory in your environment, but we recommend saving it in your Meltano project to make it easier to keep track of.
Then create a new virtual environment inside that directory:
mkdir .venv
python -m venv .venv/meltano
# Activating Your Virtual Environment
Activate the virtual environment using:
source .venv/meltano/bin/activate
If the virtual environment was activated successfully, you'll see a (meltano)
indicator added to your prompt.
TIP
Once a virtual environment is activated, it stays active until the current shell is closed. In a new shell, you must re-activate the virtual environment before interacting with the meltano
command that will be installed in the next step.
To streamline this process, you can define a shell alias that'll be easier to remember than the entire activation invocation:
# add to `~/.bashrc`, `~/.zshrc`, etc, depending on the shell you use:
alias meltano!="source $MELTANO_PROJECT_PATH/.venv/meltano/bin/activate"
# use as follows, after creating a new shell:
meltano!
You can deactivate a virtual environment by typing deactivate
in your shell.
# Install Meltano
Now that you have your virtual environment set up and running, run the following command to install the Meltano package:
pip3 install meltano
Once the installation completes, you can check if it was successful by running:
meltano --version
# Next Steps
Now that you've installed Meltano and its requirements, you can continue setting up your Meltano project by following the Getting Started guide.
# Installing on Docker
Docker is an alternative installation option to using a virtual environment to run Meltano. To use these instructions you will need to install Docker onto your computer and have it running when you execute the commands below.
# Using Pre-built Docker Images
We maintain the meltano/meltano
Docker image on DockerHub, which comes with Python and Meltano pre-installed.
To get the latest version of Meltano, pull the latest
tag. Images for specific versions of Meltano are tagged v<X.Y.Z>
, e.g. v1.55.0
.
By default, these images come with the oldest version of Python supported by Meltano, currently 3.6.
If you'd like to use Python 3.7 or 3.8 instead, add a -python<X.Y>
suffix to the image tag, e.g. latest-python3.8
and v1.54.0-python3.7
.
# download or update to the latest version
docker pull meltano/meltano
# Or choose a specific version of Meltano and/or Python:
# docker pull meltano/meltano:v1.55.0
# docker pull meltano/meltano:latest-python3.7
# docker pull meltano/meltano:v1.55.0-python3.8
# check the currently installed version
docker run meltano/meltano --version
# Initialize Your Project
Once you have Docker installed, running, and have pulled the pre-built image you can use Meltano just as you would in our Getting Started Guide. However, the command line syntax is slightly different. For example, let's create a new Meltano project:
cd /your/projects/directory
docker run -v $(pwd):/projects \
-w /projects \
meltano/meltano init yourprojectname
Then you can cd
into your new project:
cd yourprojectname
We can then start the Meltano UI. Since ui
is the default command, we can omit it.
docker run -v $(pwd):/project \
-w /project \
-p 5000:5000 \
meltano/meltano
You can now visit http://localhost:5000 to access the Meltano UI.
Now that you're successfully running Meltano, you can continue setting up your Meltano project by following the Getting Started guide.
Note that wherever you are asked to run the meltano
command, you will want to run it through docker run
as in the snippet above.
# Troubleshooting Installation
TIP
Are you having installation or deployment problems? We are here to help you. Check out Getting Help on the different ways to get in touch with us.
# Upgrading Meltano Version
We release new versions of Meltano every week. To keep tabs on the latest releases, follow along on the Meltano blog, or have a look at our CHANGELOG.
# Using the command line
You can update Meltano to the latest version by running the following command in your terminal from inside a Meltano project:
meltano upgrade
# Using Meltano UI
When an update is available, you will be informed of this automatically through a shiny blue button in the top right corner of Meltano UI:
Clicking this button will show more information and give you the option to install the update right away:
The Meltano UI will refresh automatically once installation is complete.