How to setup or install Apache Flink

Setup or install Apache Flink on a local machine

To setup or install Apache Flink for learning and local development, download the Flink binary distribution, verify Java, extract the archive, start the local cluster, and open the Flink Web UI at localhost:8081. This tutorial focuses on a single-machine Apache Flink local cluster, not a production deployment on Kubernetes, YARN, or a multi-node standalone cluster.

Apache Flink can run on the following operating systems for local setup:

• Linux
• macOS
• Windows, preferably through WSL or a shell supported by the downloaded Flink distribution

The steps below also keep the older commands shown in the screenshots for reference. Recent Flink documentation uses start-cluster.sh and stop-cluster.sh for a local cluster, while older Flink 1.x packages used scripts such as start-local.sh or start-local.bat.

Apache Flink setup requirements before installation

Before installing Apache Flink, make sure the machine has a working Java installation and enough memory for a small local cluster. For current Flink 2.x releases, Java 17 is the recommended runtime according to the Apache Flink Java compatibility documentation. Older Flink releases may use different Java versions, so always check the documentation for the exact Flink version you download.

• Java: Install a supported JDK, not only a browser plugin or partial runtime.
• Terminal access: Use Terminal on Linux or macOS. On Windows, WSL is the cleanest option for recent Flink packages.
• Archive tool: You need a tool that can extract .tgz or .zip files.
• Free port: The local Flink dashboard normally uses port 8081.

You can also review the current Apache Flink Java compatibility page before choosing a JDK.

How to check Java before installing Apache Flink

To check if Java is available, open the command prompt or terminal and enter the following command :

java -version

The output would look as shown below.

In this case, the machine has Java with the version of 1.8. For a current Apache Flink setup, compare your Java output with the Java version supported by your chosen Flink release. If you are using Flink 2.x for a new local setup, Java 17 is usually the safer choice.

If the output for the command “java -version” is not as shown in the above image, Java is not installed or the Path to Java executable is not set properly. To set up Java in your machine, please refer How to setup java.

If Java is installed but Flink still does not start, check that JAVA_HOME points to the same JDK installation that appears in java -version. A mismatch between terminal Java and environment Java is a common reason for startup errors.

Download the Apache Flink binary distribution

Once your PC or machine is ready with Java, download an Apache Flink binary distribution. Use the main binary package for local learning. Do not download the source release unless you intend to build Flink yourself. Binaries are available for download at the official download page.

For this tutorial, the original setup used the Hadoop version 2.7 and Scala 2.11 at the link. That package is useful only if you are following the old screenshots exactly. For a new installation, select the current stable binary from the Apache Flink downloads page and then follow the commands shown for your downloaded version.

If you do not need to connect Flink to Hadoop, Kafka, JDBC, or another external system immediately, install only the base Apache Flink distribution first. You can add connectors later when you start building real jobs.

# Example only: replace <version> with the folder name of the Flink release you downloaded
tar -xzf flink-<version>-bin-scala_2.12.tgz
cd flink-<version>

The downloaded file is usually more than 100MB, so wait until the archive is fully downloaded before extracting it. After extraction, open the extracted Flink folder.

The contents of the folder should look like the following.

The most important folders for a beginner are bin, conf, examples, and log. The bin folder contains scripts to start and stop Flink. The conf folder contains local configuration files. The examples folder contains sample jobs, and log helps you troubleshoot startup or job execution errors.

Start a local Apache Flink cluster

For recent Apache Flink versions on Linux, macOS, or WSL, start the local cluster from the extracted Flink folder using start-cluster.sh.

./bin/start-cluster.sh

You should see output similar to the following.

Starting cluster.
Starting standalonesession daemon on host <hostname>.
Starting taskexecutor daemon on host <hostname>.

In Windows: older Flink packages included local Windows scripts such as start-local.bat. If your downloaded distribution has a Windows batch script in the bin folder, run it from that folder. If it does not, use WSL and run the Linux command above.

In Ubuntu: the older screenshot below uses ./bin/start-local.sh. In a current Flink release, use ./bin/start-cluster.sh unless the documentation bundled with your downloaded version says otherwise.

The local cluster starts Flink background processes on your PC or machine. You can check whether the Flink processes are running with the following command.

ps aux | grep flink

The Flink Web UI should now be available through a browser at http://localhost:8081/. The dashboard should show a running cluster, the available TaskManager, task slots, and any submitted jobs.

Apache Flink jobmanager overview could be seen in the browser as above. In newer Flink versions, the dashboard wording may show Dispatcher, JobManager, TaskManager, task slots, completed jobs, and running jobs depending on the release.

Run a sample WordCount job after Apache Flink starts

After the local cluster starts, run a built-in example job to confirm that the installation can execute a job, not only open the dashboard.

./bin/flink run examples/streaming/WordCount.jar

Then check the TaskManager output log.

tail -n 20 log/flink-*-taskexecutor-*.out

If the job completes, the Web UI should show the job in the completed jobs section. If the command fails, read the error message first and then check the files in the log folder.

Stop the Apache Flink local cluster

Stop the local cluster when you finish testing. This releases the local processes and keeps port 8081 available for the next run.

./bin/stop-cluster.sh

In Windows, if your older Flink package includes stop-local.bat, running the command from the <flink-folder>/bin/ folder should stop the local daemon. For recent packages without Windows batch scripts, stop the cluster from WSL with ./bin/stop-cluster.sh.

In Ubuntu, the older command ./bin/stop-local.sh may apply only to older Flink versions. In current Flink documentation, the local cluster is stopped with ./bin/stop-cluster.sh.

Fix common Apache Flink local installation issues

• java -version fails: install a supported JDK and set the Java path correctly.
• Flink starts but localhost:8081 does not open: wait a few seconds, confirm the processes are running, and make sure another application is not using port 8081.
• Script not found: confirm that you are inside the extracted Flink root folder and that you are using the script name available in your Flink version.
• Permission denied on Linux or macOS: make the script executable with chmod +x bin/*.sh or run it from a shell that can execute the file.
• Job fails after the cluster starts: check the files in the log folder and confirm that your Java version matches the Flink release.

Apache Flink local setup QA checklist

1. The tutorial tells readers to download the Apache Flink binary distribution, not the source release.
2. The Java requirement is tied to the selected Flink version, with Java 17 recommended for current Flink 2.x setup.
3. The local cluster start command uses ./bin/start-cluster.sh for current Linux, macOS, and WSL setups.
4. The article explains that older screenshots may show start-local.sh or start-local.bat.
5. The verification step includes both localhost:8081 and a sample WordCount job.
6. The stop command uses ./bin/stop-cluster.sh for current Flink versions.

FAQs on installing Apache Flink locally

Can you run Apache Flink locally?

Yes. Apache Flink can run as a local cluster on a single machine. This is useful for learning Flink, testing examples, and developing jobs before using a larger deployment.

Which Java version should I use for Apache Flink setup?

Use the Java version supported by the Flink release you install. For current Flink 2.x releases, Java 17 is the recommended runtime. If you are using an older Flink release, check that release documentation before installing Java.

Why does Apache Flink not open at localhost:8081?

First confirm that the cluster started without errors. Then check whether Flink processes are running, whether port 8081 is already used by another application, and whether the log folder contains startup errors.

Do I need Hadoop to install Apache Flink locally?

No. Hadoop is not required for a basic local Apache Flink setup. Install the base Flink binary first, then add Hadoop or other connectors later only if your jobs need them.

Which is better, Apache Flink or Kafka?

Apache Flink and Apache Kafka solve different parts of a streaming system. Kafka is commonly used to store and transport event streams, while Flink is used to process streams and run stateful computations. Many systems use both together.

Apache Flink installation summary and next step

In this Flink Tutorial, we have seen how to set up or install Apache Flink to run as a local cluster. You verified Java, downloaded and extracted the Flink binary, started the local cluster, opened the Web UI, ran a sample job, and stopped the cluster. In the next tutorial, we shall observe how to submit a job to the Apache Flink local cluster.

For the most current commands and version-specific notes, refer to the official Apache Flink local installation guide.