README.md

pkgx is a single, standalone binary that can run anything.   

 

Quickstart

brew install pkgxdev/made/pkgx

• docs.pkgx.sh/installing-w/out-brew
• Migrating from v0

 

Run Anything

$ deno
command not found: deno

$ pkgx deno
Deno 1.36.3
> ^D

$ deno
command not found: deno
# ^^ nothing was installed; your system remains untouched

Run Any Version of Anything

$ pkgx node@14 --version
Node.js v14.21.3

$ pkgx python@2 --version
Python 2.7.18

Run Anywhere

• macOS

  
  

  • macOS >= 11
  • x86-64 & Apple Silicon
• Linux

  
  

  • glibc >=2.28 repology
  • x86_64 & arm64
• Windows

  
  

  WSL2; x86-64. Native windows is planned.

• Docker

  
  

  $ pkgx docker run -it pkgxdev/pkgx
  
  (docker) $ pkgx node@16
  Welcome to Node.js v16.20.1.
  Type ".help" for more information.
  >

  Or in a Dockerfile:

  FROM pkgxdev/pkgx
  RUN pkgx [email protected] task start

  Or in any image:

  FROM ubuntu
  RUN curl https://pkgx.sh | sh
  RUN pkgx [email protected] -m http.server 8000

  docs.pkgx.sh/docker

• CI/CD

  
  

  - uses: pkgxdev/setup@v1
  - run: pkgx shellcheck

  Or in other CI/CD providers:

  $ curl https://pkgx.sh | sh
  $ pkgx shellcheck

  docs.pkgx.sh/ci-cd

• Scripts

  
  

  #!/usr/bin/env -S pkgx +git [email protected]
  
  # python 3.12 runs the script and `git` is available during its execution

  docs.pkgx.sh/scripts

• Editors

  
  

  $ cd myproj
  
  myproj $ env +cargo
  (+cargo) myproj $ code .

  Or use dev; a separate tool that uses the pkgx primitives to automatically determine and utilize your dependencies based on your project’s keyfiles.

  $ cd myproj
  
  myproj $ dev
  env +cargo +rust
  
  (+cargo+rust) my-rust-project $ code .

  docs.pkgx.sh/editors

 

Shell Integration

pkgx puts the whole open source ecosystem at your fingertips and its optional shell integration makes workflows with that open source even more seamless.

$ env [email protected]    # do `pkgx integrate --dry-run` first
added ~/.pkgx/go.dev/v1.16 to environment

(+go) $ go
Go is a tool for managing Go source code.
#…

(+go) $ env | grep go
PATH=~/.pkgx/go.dev/v1.16.15/bin:$PATH
LIBRARY_PATH=~/.pkgx/go.dev/v1.16.15/lib

(+go) $ env -go
removed ~/.pkgx/go.dev/v1.16 from environment

$ go
command not found: go

Tools are available for the duration of your terminal session. If you need them for longer, eg. pkgx install go.

docs.pkgx.sh/shell-integration
docs.pkgx.sh/pkgx-install

dev

dev is a separate tool that leverages pkgx's core features to auto-detect and install project dependencies, seamlessly integrating them into your shell and editor.

my-rust-proj $ dev    # do `pkgx integrate --dry-run` first
dev: found Cargo.toml; env +cargo +rust

(+cargo+rust) my-rust-proj $ cargo build
Compiling my-rust-proj v0.1.0
#…

The dev tool requires our shell integration to work.

docs.pkgx.sh/dev

 

Getting Started

brew install pkgxdev/made/pkgx

no brew? docs.pkgx.sh/installing-w/out-brew

Integrating with your Shell

pkgx integrate --dry-run   # docs.pkgx.sh/shell-integration

Further Reading

docs.pkgx.sh is a comprehensive manual and user guide for pkgx.

 

Contributing

• To add packages see the pantry README
• To hack on pkgx itself; clone it and then pkgx deno task to list entrypoints for hackers

If you have questions or feedback:

• github.com/orgs/pkgxdev/discussions
• x.com/pkgxdev (DMs are open)