Publishing Packages to Ballerina Central

The sections below include information about working with library packages.

Creating a Library Package

Execute the bal new -t lib command to create a new library package.

bal new hello --template lib

This will create a new Ballerina package with a hello function. The bal new command generates the below for a library package:

cd hello
tree .
    ├── Ballerina.toml 
    ├── hello.bal

0 directories, 3 files

It creates the Ballerina.toml file. Apart from it, the hello.bal source file and the files are created. For more information on these, see Package Layout.

The Ballerina.toml file will include the content below.

org = "user"
name = "hello"
version = "0.1.0"

observabilityIncluded = true

Execute the bal build -c to build the Ballerina archive of the package.

bal build -c
Compiling source

Creating bala

Publishing a Library Package to Ballerina Central

Now, that you have a package to share with others, it can be published to the Ballerina Central.

Ensure the package works as intended because a publish is permanent. Once published to Ballerina Central, the version can never be overwritten and the package cannot be removed. However, the number of versions of a package that can be pushed to Ballerina Central is not restricted.

Tip: As a precaution, use the local repository first to test out the functionality of the library package before publishing it to Ballerina Central.

Preparing for Publishing

  1. Create an account on Ballerina Central. To register, visit the home page and log in via a Google or GitHub account.

  2. Navigate to the Dashboard and acquire an access token.

  3. Download and place the Settings.toml file in your home repository (<USER_HOME>/.ballerina/). If you already have a Settings.toml file configured in your home repository, follow the other option and copy the access token into the Settings.toml. Else, if you are connected to the internet via an HTTP proxy, add the following section to Settings.toml and change accordingly.

host = "localhost"
port = "3128"
username = ""
password = ""


When you push a package to Ballerina Central, the organizations are validated against the value of the org field defined in the Ballerina.toml file. Therefore, when you have more than one organizations in Ballerina Central, pick the organization name that you intend to push the package into, set that as the org in the Ballerina.toml file inside the package directory, and rebuild the package.

Also, organization names starting with ballerina (e.g., ballerina, ballerinax, ballerinai, etc.) are reserved for system use, and thereby, you cannot publish any packages starting with the ballerina prefix to Ballerina Central. Therefore, if you have used a name pattern matching this, update the Ballerina.toml and rebuild the package.

Publishing the Package

Now, that you are ready to publish, execute the command below to publish the package to Ballerina Central.

bal push

Using the Packages in Ballerina Central

After publishing your first package, you can create a second package and use the already-published package in it.

Any package published in Ballerina Central is public and they can be used in packages as explained in Dependencies.