Apple Pkl: Code Example, Concepts & How to Get Started

Apple Pkl Code Example, Concepts & How to Get Started Blog Banner

What Is Apple Pkl? 

In early 2024, Apple launched Pkl (pronounced “Pickle”), an innovative file format and programming language that will revolutionize configuration management. Pkl is the first formal language designed specifically for configuration data. 

Pkl is flexible, secure, and provides built-in error detection features. It integrates with popular programming languages, with the ability to automatically generate code in the language of your choice, and also supports many popular Integrated Development Environments (IDEs). 

Apple Pkl is open source, using the Apache 2.0 license. You can download it from the official GitHub repo.

This is part of a series of articles about configuration management.

Why Use Pkl? 

Pkl is a versatile programming language that can manage a wide range of configuration-related data. Key use cases include:

  • Infrastructure configuration: Any infrastructure component, including networks, servers, cloud services, and containers, can be configured with Pkl. The language can generate configuration files in multiple formats like XML, JSON, and YAML.
  • Application configuration: Pkl can be useful for settings of customer facing elements like user interfaces, and also for backend features, such as preferences and internal software parameters. It can automatically produce configuration code in popular programming languages including Java, Kotlin, Swift, and Go.
  • Environment setup: Pkl can be used to configure a variety of environments such as staging, production, testing, and development. It is also useful to generate artifacts such as claims, environment variables, and credentials.

In these use cases and others, Pkl is the high level language defining the configuration, and based on this definition, it can generate the configuration files or artifacts needed for low-level components.

Pkl Example

Here is a simple example shared in the Pkl documentation. Consider the following file with a set of key-value pairs. This is a valid .pkl file.

name = "Pkl: Configure your Systems in New Ways"
attendants = 100
isInteractive = true
amountLearned = 13.37

If you save this as example.pkl and run the command:

pkl eval /Users/me/tutorial/intro.pkl

Pkl returns the following output, indicating that it accepts and understands the content of the file:

name = "Pkl: Configure your Systems in New Ways"
attendants = 100
isInteractive = true
amountLearned = 13.37

Now, you can ask Pkl to produce a configuration file in any format you need. For example, to create a JSON file, you can run this command:

pkl eval -f json /Users/me/tutorial/intro.pkl

Pkl returns a JSON file containing your configuration:

  "name": "Pkl: Configure your Systems in New Ways",
  "attendants": 100,
  "isInteractive": true,
  "amountLearned": 13.37

Or you can run this command to generate a PropertyList format:

pkl eval -f plist /Users/me/tutorial/intro.pkl

Here is what Pkl comes up with:

  Pkl: Configure your Systems in New Ways

Pkl Concepts 

Pkl goes far beyond basic key-value pairs as we saw in the example. Let’s see how the language manages complex configurations with various structures and formats.


As configurations grow in size and complexity, their understanding and maintenance become increasingly challenging. Pkl can help reduce this complexity. It can define similar configuration elements by focusing on their unique attributes, create simplified forms of common configuration elements, and decouple configuration structure from actual configuration data. 

In addition, the language can reduce configuration enumeration, allowing users to specify configuration in simple terms and automatically generate complex configuration syntax.

Evaluation and Rendering

Pkl code is structured into modules. Each module is represented by a file. Evaluating a module creates an in-memory data model similar to a JSON data model. If the evaluation is successful, the Pkl evaluator transforms the data model into meaningful representation, and provides status code zero. If it fails, it generates error messages, and returns a non-zero status code.

In Pkl, the process of transforming a data model into another useful representation is known as ‘rendering’ the model. Pkl provides renderers for several data formats, including JSON, Jsonnet, Java properties, Property Lists, XML, and YAML. You can support your own custom formats by creating a customized renderer in either Pkl or Java.

Immutability and Secure Isolation

All data within the Pkl system is immutable. Any data manipulation results in a new data value, while the original value remains intact. This makes it easier to work with and manage configurations, and avoids many possible errors.

In addition, Pkl was designed to prevent security threats like code and command injection. Pkl code evaluation occurs within a tightly controlled environment. Apart from a limited number of exceptions, the interaction of Pkl code with the environment is highly restricted.

According to the makers of Pkl, the severest consequence of flawed or malicious Pkl code could be the exhaustion of CPU and memory resources, which will eventually lead to the Pkl evaluator being terminated. Pkl is designed to ensure code cannot be used to manipulate other aspects of the system it runs on.

Module Importing

Modules in Pkl can use other modules by importing them. This makes it possible for a large module to be broken down into more manageable pieces, making it easier to maintain. Pkl uses a customizable security policy to ensure that the process of importing is efficient and secure.

Configuration Schemas

In Pkl, configuration is represented as structured data. Users can use this structure to create formal schemas of configuration. A schema is a group of classes that define configuration properties, such as default settings, types, and constraints. 

Schemas are not mandatory in Pkl, and might require a bit more effort to define, but can provide multiple benefits. For example, they enable generating automated documentation, strict validation of configurations during the development lifecycle, and support for schema-aware tools like IDEs or code editors.


Pkl allows users to create templates for both individual objects and entire modules. These templates are like a mold that can be transformed into actual configurations. Users can start from a template, fill in the necessary information, and overriding default settings as required. The ability to share template modules can make configuration much easier to maintain and share across teams, organizations, and development communities.

Getting Started with Apple Pkl 

The command-line interface (CLI) of Pkl is designed to evaluate Pkl modules, presenting the results either directly on the console or saving it in a file format. 

Pkl Versions

As of the time of this writing, the Pkl CLI is available for several platforms: 

  • Native macOS application for amd64 architecture
  • Native Linux application for amd64 architecture
  • Native Linux app for aarch64 architecture
  • Native Alpine Linux application for amd64
  • Java-based application compatible with Java 8/11/14

The Pkl documentation recommends using native apps for macOS and Linux users, because they are faster to load and execute Pkl code. Those working on other platforms can use the Java application which has broad compatibility and smaller binary size. 

It’s worth noting that both development and release versions of the Pkl CLI can be manually downloaded and installed.

Installing Pkl

We’ll cover how to install the Pkl native applications for macOS (amd64) and Linux (amd64). See the official documentation for other versions.

macOS native application (amd64)

Downloading the Pkl file using this command (adjust the version in the URL to the latest version):

curl -L -o Pkl

Give the downloaded file executable rights:

chmod +x Pkl

Run the program and confirm its version:

./Pkl --version

You should see the following output or similar, indicating Pkl is properly installed:

Pkl 0.25.2 (macOS, native)

Linux native application (amd64)

Note: The Linux version of Pkl relies on dynamic linkage with glibc and libstdc++. 

Download the Pkl file using this command (adjust the version in the URL to the latest version):

curl -L -o Pkl

Modify the permissions of the file to make it executable:

chmod +x Pkl

Start the program and verify its version:

./Pkl --version

You should see output similar to this:

Pkl 0.25.2 (Linux, native)

Try Configu for free
Painless end-to-end configuration management platform
Get Started for Free