Pkl 0.33 Release Notes

Pkl 0.33 was released on XXX.
The latest bugfix release is 0.33.0. (All Versions)

The next release (0.34) is scheduled for February 2027. To see what’s coming in the future, follow the Pkl Roadmap.

Please send feedback and questions to GitHub Discussions, or submit an issue on GitHub.

Pkl is hosted on GitHub. To get started, follow Installation.

Noteworthy 🎶

CLI Changes

Default file locations

For new setups, the CLI no longer stores anything under ~/.pkl (#1809).

It uses XDG-style locations on Unix and Known Folder locations on Windows:

Concern Unix (Linux/macOS) Windows Legacy fallback

Concern	Unix (Linux/macOS)	Windows	Legacy fallback
Package cache	`~/.cache/pkl`	`$LOCALAPPDATA/pkl/Cache`	none
Settings file	`~/.config/pkl/settings.pkl`	`$APPDATA/pkl/settings.pkl`	`~/.pkl/settings.pkl`
CA certificates	`~/.config/pkl/cacerts`	`$APPDATA/pkl/cacerts`	`~/.pkl/cacerts`
REPL history	`~/.local/state/pkl/repl-history`	`$LOCALAPPDATA/pkl/repl-history`	none

Package cache

~/.cache/pkl

$LOCALAPPDATA/pkl/Cache

none

Settings file

~/.config/pkl/settings.pkl

$APPDATA/pkl/settings.pkl

~/.pkl/settings.pkl

CA certificates

~/.config/pkl/cacerts

$APPDATA/pkl/cacerts

~/.pkl/cacerts

REPL history

~/.local/state/pkl/repl-history

$LOCALAPPDATA/pkl/repl-history

none

On every OS, these locations can be overridden with XDG-style env vars. For example, setting XDG_CACHE_HOME will configure the cache directory.

Note that the existing ~/.pkl/cache directory is ignored, so Pkl will download packages to populate its cache if configured to do so.

Breaking Changes 💔

Removal of macOS amd64 (Intel) Binaries

Native pkl and pkldoc binaries for Intel Mac systems are no longer published with Pkl releases.

To continue running new Pkl releases on these systems, use an appropriate Java runtime and the jpkl and jpkldoc Java executables.

Type check changes for `Class<T>`

In prior versions of Pkl, type arguments to the Class type were erased. Any Class value would typecheck against Class<T> for any value of T.

In Pkl 0.33, this erasure has been removed. A Class value typechecked against Class<T> must be a subclass of T.

If T does not resolve to a class type (i.e. it is a union type, nullable type, string literal type, parameterized type, or nothing), the type check will always fail.

Standard library `external` module properties are now marked `const`

Previously, module properties in pkl:math and pkl:release could be overriden by amending the module. Doing this makes little sense—these value are constants and overriding them by amending their module would be odd.

This is a breaking change for code that looks like this:

bogusMath = (import("pkl:math")) {
  minInt = -1
}