poks 0.11.0

A lightweight archive downloader for pre-built binary dependencies.

Poks

---

Source Code: https://github.com/cuinixam/poks

---

A lightweight, cross-platform archive downloader for pre-built binary dependencies. Inspired by Scoop, Poks provides a uniform way to install and manage developer tools using simple JSON manifests.

While Poks includes a CLI, its main purpose is to be used programmatically to manage dependencies in your Python projects and automation scripts.

Features

• Programmatic API: First-class Python support for integrating into your tools
• Cross-Platform: Works on Windows, Linux, and macOS
• No Admin Rights: Installs tools in user space
• Deterministic: Pin exact versions in manifests for reproducible builds
• Relocatable: The apps directory is self-contained and portable

Installation

pip install poks

For CLI-only usage:

pipx install poks

Concepts

• App: A tool or dependency you want to install (e.g., CMake, a compiler toolchain). Each app has a name and one or more versions.
• Manifest: A JSON file that describes an app — its download URLs, checksums, and platform-specific archives. One manifest per app (e.g., cmake.json). See examples/cmake.json.
• Bucket: A git repository containing a collection of manifests. Buckets are how manifests are shared and distributed.
• Config file: A JSON file (poks.json) that ties it all together — it lists which buckets to use and which apps (with versions) to install from them. See examples/poks.json.

Installing apps

From a config file

Use a config file when you want to define a reproducible set of tools for a project. The config references one or more buckets and lists the apps to install from them.

poks install --config poks.json

From a bucket

Install a single app directly, without a config file. Poks looks up the app's manifest in the specified bucket.

poks install --app cmake --version 3.28.1 --bucket main
poks install --app cmake --version 3.28.1 --bucket https://github.com/poks/main-bucket.git
poks install --app cmake --version 3.28.1   # searches all local buckets

From a manifest file

Install directly from a local manifest file — no bucket needed. Useful for testing a manifest before publishing it to a bucket. The app name is derived from the filename.

poks install --manifest cmake.json --version 4.2.3

Platform filtering

Apps in a config file can be restricted to specific operating systems or architectures using the os and arch fields. Apps that don't match the current platform are silently skipped.

{
    "apps": [
        { "name": "cmake", "version": "3.28.1", "bucket": "main" },
        { "name": "mingw-tools", "version": "1.0.0", "bucket": "extras", "os": ["windows"] },
        { "name": "build-essential", "version": "1.0.0", "bucket": "extras", "os": ["linux", "macos"] }
    ]
}

Supported values — os: windows, linux, macos; arch: x86_64, aarch64. When omitted, the app is installed on all platforms.

Other commands

poks uninstall cmake@3.28.1       # specific version
poks uninstall cmake              # all versions
poks uninstall --all              # everything
poks search cmake                 # search across local buckets
poks list                         # list installed apps
poks unpack archive.tar.gz -o ./out  # extract an archive directly
poks convert-scoop manifest.json  # convert a Scoop manifest to Poks format

Python API

Poks is designed to be used programmatically. See examples/ for complete scripts.

from pathlib import Path
from poks.poks import Poks

poks = Poks(root_dir=Path.home() / ".poks")

poks.install(Path("poks.json"))                              # from config file
poks.install_app("cmake", "3.28.1", bucket="main")           # from bucket
poks.install_from_manifest(Path("cmake.json"), "3.28.1")     # from manifest file

Manifest format

For the manifest schema and detailed specifications, see docs/specs.md.

Contributing

This project uses pypeline for build automation and uv for dependency management.

# Install pypeline
uv tool install pypeline-runner

# Run full pipeline (lint + tests)
pypeline run

For AI agents, see AGENTS.md.

Credits

This package was created with Copier and the browniebroke/pypackage-template project template.