DOCSEARCHbyAlgolia
Submit Docs

pkgx

repository·main·Indexed 27 days ago

https://github.com/pkgxdev/pkgx

A lightweight, standalone binary designed to run any tool or any version of a tool without polluting the host system. It acts as a composable primitive for creating virtual environments, scripts, and development workflows, downloading tools to ~/.pkgx. It includes a CLI for running programs with specific versions (e.g., pkgx node@14), querying available packages, and dumping environment configurations in shell or JSON formats.

Tokens
8.4K
Snippets
37
Records
98
Agent score
91%

What's inside pkgx

  1. Overview of the `pkgx` ecosystem

    main

    pkgx is a standalone 4 MiB binary designed to run any tool without permanent installation. It serves as a primitive for several ecosystem tools:

    • dev: Creates "virtual environments" for projects and toolsets using shellcode and pkgx.
    • pkgm: Installs pkgx packages to /usr/local.
    • mash: A package manager for scripts that leverages pkgx to access the open source ecosystem.
    • pkgo: Simplifies the installation of complex open-source tools (e.g., Stable Diffusion WebUI) by using pkgx under the hood.

  3. Use pkgx in CI/CD

    main

    For GitHub Actions, use the pkgxdev/setup action. For other CI providers, use the standard shell installation script.

    # GitHub Actions
- uses: pkgxdev/setup@v4
- run: pkgx shellcheck
    # Other CI providers
curl https://pkgx.sh | sh
pkgx shellcheck

  7. Use `pkgx` as a shebang for scripts

    main

    You can use pkgx in a script's shebang line to automatically provide the required runtime and dependencies. When using env, you must use the -S parameter to pass multiple arguments to pkgx.

    Example for a Python script:

    #!/usr/bin/env -S pkgx python@3.9

import sys
print(sys.version)
    #!/usr/bin/env -S pkgx python@3.9

import sys

print(sys.version)

  9. Use pkgx with Docker

    main

    You can run pkgx using the official Docker image pkgxdev/pkgx.

    To run an interactive session:

    docker run -it pkgxdev/pkgx

    To run a specific command with specific versions:

    docker run pkgxdev/pkgx +python@3.10 node@22 start

    To use it in a Dockerfile:

    FROM pkgxdev/pkgx
RUN pkgx +node@16 npm start

  11. Write scripts with pkgx shebangs

    main

    Use the +pkg syntax in a shebang to load specific tools and versions for a script. Tools loaded this way are not installed to your system and do not pollute it; they are downloaded to ~/.pkgx.

    #!/usr/bin/env -S pkgx +git python@3.12

# python 3.12 runs the script and git is available during its execution
    #!/usr/bin/env -S pkgx +python@3.11 uv run

# /// script
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
# ... script logic ...

  12. Run specific versions using SemVer

    main

    Use the @ syntax or standard SemVer operators to specify which version of a package to run:

    • @<version>: Specific version (e.g., postgres@12).
    • ^<version>: Caret requirement (e.g., postgres^12).
    • "<range>": Range requirements (e.g., "postgres>=12<14").
    • =<version>: Exact version (e.g., deno=1.35.3).
    $ pkgx postgres@12 --version
$ pkgx postgres^12 --version
$ pkgx "postgres>=12<14" --version
$ pkgx deno=1.35.3 --version