Installing Ballerina
The sections below include information about installing Ballerina.
Table of contents Expand all Collapse all
Installing Ballerina via Installers
Follow the instructions below to install the latest Ballerina version using the installer. The installer will automatically uninstall the old Ballerina version if you have one already installed.
Info: Ballerina installers support operating systems such as Windows, Ubuntu, Red Hat Enterprise Linux, macOS, and Cent OS. If you are using an unsupported operating system, install via the Ballerina language ZIP file.
Installing on macOS
Download the package file and double-click on it to launch the installer. The installer guides you through the installation process and installs the Ballerina distribution in the /Library/Ballerina
directory.
Info: Alternatively, you can execute the command below to install Ballerina in macOS using Homebrew. Homebrew installs the Ballerina distribution in the
/usr/local/Cellar/ballerina/<BALLERINA-VERSION>/libexec
directory.
brew install ballerina
The package automatically sets your PATH environment variable for you. You may need to restart any open Terminal sessions for the change to take effect.
Installing on Windows
Download the MSI file and double-click on it to launch the installer. The installer guides you through the installation process and installs the Ballerina distribution in the C:\Program Files\Ballerina
directory.
The installer should put the C:\Program Files\Ballerina\<BALLERINA-DIRECTORY>\bin
directory in your PATH environment variable. You may have to restart any open command prompts for the change to take effect.
Installing on Linux
Download the DEB file or RPM file and double-click on it to launch the installer. The installer guides you through the installation process and installs the Ballerina distribution in the /usr/lib64/ballerina
directory.
Info: Alternatively, you can use either of the commands below to install Ballerina using the downloaded DEB or RPM file. Replace the
ballerina-linux-installer-x64-<BALLERINA-VERSION>.deb
orballerina-linux-installer-x64<BALLERINA-VERSION>.rpm
with the actual file path.
For example, for the DEB file:
dpkg -i ballerina-linux-installer-x64-1.2.4.deb
For example, for the RPM file:
rpm -i ballerina-linux-installer-x64-1.2.4.rpm
Installing via the Ballerina Language ZIP File
Note: Before you install Ballerina using the ZIP file, ensure that you have a supported Java Runtime Environment (JRE) installed. It is recommended to use the AdoptOpenJRE version 1.8 or above.
-
Download the Ballerina language ZIP file (md5, SHA-1, asc) and unzip it to a preferred location using an archiver tool of your choice. This creates a directory named ballerina-
in your system. -
Follow either of the steps below depending on your operating system to configure your system environment to run Ballerina:
- For Linux or macOS: set the PATH environment variable to point to the bin directory of the unzipped Ballerina distribution.
- For Windows: add a new environment variable specifying the following values:
- Variable name: PATH
- Variable value: The location of the bin directory of the unzipped Ballerina distribution. For example,
C:\Program Files\Ballerina\ballerina-<VERSION>\bin
Updating Ballerina
If you already have a jBallerina version above 1.1.0 installed, you can use the update tool to update to the latest jBallerina version by executing either of the commands below.
Command | Description |
---|---|
ballerina dist update |
Update to the latest patch version of the active distribution |
ballerina dist pull jballerina-<JBALLERINA-VERSION> |
Fetch a specific distribution and set it as the active version |
For more information, see Keeping Ballerina Up to Date.
Building from Source
Alternatively, follow the instructions below to build Ballerina from the source.
Setting Up the Prerequisites
You need to download and install the below to build the Ballerina modules.
- Java SE Development Kit (JDK) version 8 (from one of the following locations)
- Node.js (version 8.9.x)
- npm (version 5.6.0 or later)
Obtaining the Source Code
Follow the steps below to obtain the Ballerina source code.
-
Execute the command below to clone the ‘ballerina-lang’ source repository.
git clone --recursive https://github.com/ballerina-platform/ballerina-lang.git
Tip: If you have already forked the repository to your GitHub account, then execute the below command replacing
<YOUR-GITHUB-USERNAME>
with your Git username.git clone --recursive https://github.com/<YOUR-GITHUB-USERNAME>/ballerina-lang.git
-
Execute the command below to update the Git submodules.
git submodule update --init
Building the Source
Follow the steps below to build the project of the obtained source.
-
Navigate to the root directory of the Ballerina repo (i.e.,
<BALLERINA_PROJECT_ROOT>
) and execute one of the Gradle commands below to build the project using Gradle.- On Unix/macOS:
./gradlew build
- Windows:
gradlew build
- On Unix/macOS:
-
Extract the built Ballerina distributions created in the locations below:
- Runtime only:
<BALLERINA_PROJECT_ROOT>/distribution/zip/jballerina/build/distributions/jballerina-<version>-SNAPSHOT.zip
- Runtime and tools (e.g., Ballerina Language Server):
<BALLERINA_PROJECT_ROOT>/distribution/zip/jballerina-tools/build/distributions/jballerina-tools-<version>-SNAPSHOT.zip
- Runtime only:
Note: If you face an IOException error stating “Too many open files”, this is due to the default number of possible open files being set to a lower number on your operating system than required for Ballerina to be compiled. You may have to increase the number of open files/file descriptors (FD) on your operating system to 1000000 (or higher).
Uninstalling Ballerina
Usually, the installation location is /Library/Ballerina/distributions
in macOS, /usr/lib64/Ballerina/distributions
in Linux, and C:\Program Files\Ballerina\distributions
in Windows. You can either remove a particular jBallerina version or all the jBallerina versions installed in these locations.
To remove:
- a specific jBallerina version (via the update tool): execute
ballerina dist remove
- all the installed jBallerina versions: delete the
/../Ballerina
directory in the respective installation location
What’s Next?
Once you have successfully installed Ballerina, click the links below to set up your IDE.
Tip: To get help when you work with Ballerina, see Community.