Basics

pkgx works in the terminal. The instructions on this page are aimed at people who aren't developers and are new to the Terminal. So it's pretty basic. And there will be a lot of examples.

If you don't know how to use the terminal, please do a web search for "unix terminal" and read a little bit before trying anything here. You should at least understand how to read paths (e.g. "~/" vs "/"), what a symlink is, how the Terminal finds commands or tools to run (the PATH variable), and what wget is.

Installing pkgx

If you are on Windows, you first need to install Windows Subsystem for Linux (WSL).

In the macOS or Linux terminal (Windows users need to use the WSL terminal), just type this command in.

curl -Ssf https://pkgx.sh | sh

The installer will add the pkgx script to your /usr/local/bin.

pkgx will be installed to ~/.pkgx.

The pkgx installer is located at https://pkgx.sh. When that webpage is loaded by curl, it returns the installer instead of the webpage.

Updating pkgx

To update pkgx, run the same installer.

curl -Ssf https://pkgx.sh | sh

Or you can have tea update itself:

pkgx --sync +pkgx.sh

To update pkgx’s pantry run pkgx --sync.

$ pkgx --sync
# ^^ inside a dev env this also updates the packages in that env

What are Package Managers?

Package managers automate installing, upgrading, configuring, and removing software.

pkgx is the next-generation, cross-platform package manager.

There are basically 2 types of package managers: OS and source code package managers. An OS package manager installs tools that you can use in the terminal. A source code package manager installs libraries and source code files that a developer would use to create tools.

Existing OS package managers.

• Homebrew (macOS and Linux)
• apt (Linux)
• Chocolatey (Windows)

Existing source code managers (these run on all platforms).

• npm
• pip
• gem

pkgx aims to work with both os and source code. At first, the focus is on managing source code (because that same source code is going to be used to then build everything else later on down the road).

If you use one of the other package managers, pkgx isn't trying to replace the existing tools. pkgx's infrastructure is being designed so existing package managers will be able to use it. If you are involved in the other package managers, we really hope you are willing to consider our infrastructure.

Find pkgx Packages

There is a lot of room for improvement here. The packages are listed on pkgx's front page, pkgx.dev, or the dedicated packages page, pkgx.dev/pkgs, or you can view all versions, https://tea.xyz/bottles/.

Here's a short quick list of some useful tools.

• ffmpeg
• htop
• jq
• mc
• neovim
• nmap
• pcre
• prettyping
• VHS
• wget
• youtube-dl

And here is a short quick list of some compilers and interpreters.

• bun
• c/c++/etc
• deno
• go
• haskell
• lua
• node
• perl
• python
• ruby
• rust
• tcl

Install packages

In its most basic form, pkgx will install a package if needed and run the command.

> pkgx wget
 ✓  ~/.pkgx/gnu.org/wget/v1.21.4
wget: missing URL
Usage: wget [OPTION]... [URL]...

Try `wget --help' for more options.

If you really want to install something without running it, specify the package namespace and run echo -n.

pkgx +pkg echo -n

Example.

> pkgx +gnu.org/wget echo -n
 ✓  ~/.pkgx/curl.se/ca-certs/v2023.12.12
 ✓  ~/.pkgx/openssl.org/v1.1.1w
 ✓  ~/.pkgx/gnu.org/coreutils/v9.4.0
 ✓  ~/.pkgx/gnu.org/wget/v1.21.4
> which wget
wget not found
> pkgx +gnu.org/wget which wget
/Users/max/.pkgx/gnu.org/wget/v1.21.4/bin/wget

pkgx Execution

This is how we'd execute wget.

pkgx wget http://example.com

You can also execute wget by specifying the path directly.

~/.pkgx/gnu.org/wget/v\*/bin/wget http://example.com

Here's a different example. This runs the Python "Hello, World" example. Installing and running Python has never been easier.

> echo 'print("Hello, World")' | pkgx python
Hello, World

Or

> pkgx +python.org python -c 'print("Hello, World")'
Hello, World

Here is a Python script. Use TextEdit, Notepad, or a Terminal editor to create this file. Save this code and name it "hello-world.py".

#!/usr/local/bin/pkgx python

print("Hello, World")

Run it like this.

> chmod 755 hello-world.py
> ./hello-world.py
Hello, World

pkgx PATH

Note, pkgx doesn't add anything it installs to the PATH. As shown above, use pkgx to run stuff or you can execute the command directly. If you really want to leave pkgx off, then you can create a symlink.

cd /usr/local/bin
ln -s ~/.pkgx/gnu.org/wget/v\*/bin/wget

You can also symlink directly to pkgx, it will execute the symlink name.

sudo ln -s pkgx /usr/local/bin/wget

You can also create shell aliases or wrapper scripts. Here is an alias. Put this in ~/.zshrc

alias foo='pkgx +foo/bar foo'

Here is a shell script. Put this in /usr/local/bin

#!/bin/sh
exec pkgx +foo/bar foo "$@"

Install a Specific Package Version

Specify a specific version of a package.

pkgx +python.org=3.10.8 python

Specify a minimum version. This will run the latest python 3.10.x.

pkgx +python.org^3.10.0 python

This will run the latest python 3.x.

pkgx +python.org^3.10 python

Do not modify the version symlinks in ~/.pkgx/, for example.

ls -l ~/.pkgx/lua.org:
total 0
lrwxr-xr-x  1 u0076374  wheel    6 Dec  3 01:26 v* -> v5.4.4
lrwxr-xr-x  1 u0076374  wheel    6 Dec  3 01:26 v5 -> v5.4.4
lrwxr-xr-x  1 u0076374  wheel    6 Dec  3 01:26 v5.4 -> v5.4.4
drwxr-xr-x  7 u0076374  wheel  224 Dec  1 11:03 v5.4.4

The symlinks in those directories are for you so you can access specific versions. Changing them won't alter what version tea runs. Use the tea +pkg=version format to control what tea uses.

Uninstalling Packages

Packages are self-contained. Just remove the directory for the package.

rm -r ~/.pkgx/**pkg_name**

If you create symlinks, aliases, or wrapper scripts (see discussion of the path), then remove those too.

Upgrading Packages

Some utilities will try to update themselves, but you shouldn't do that. For example, you don't want to do this. It defeats the purpose of having versioned installs.

pkgx +python.org=3.10.8 pip install --upgrade pip <-- DON'T DO THIS

Use pkgx --sync to install newer versions.

Installing "Globally" into a Package Silo

pkgx's packages are installed as siloed virtual environments. You may not want to install other packages into them.

pkgx +python.org pip install some_package

The package will be installed to ~/.pkgx/python.org/v3.11.0/lib/python3.11/site-packages.

pkgx -X npm install -g some_package

The package will be installed to ~/.pkgx/npmjs.com/v9.0.1/lib/node_modules. This probably isn't what you want.

Summary of steps

• Install pkgx
• Find a package that pkgx has pkged
  • The pkgx.dev website lists all of the packages it supports.
• Install and use the package
  • pkgx +pkg cmd [args]
  • Optional: symlink e.g ln -s pkgx /usr/local/bin/**cmd_name**
  • Optional: alias (see above)
  • Optional: wrapper shell script (see above)