Get started

Thanks for giving pls a try. We hope you like using it as much as we do.

Prerequisites

• macOS or Linux: Windows is currently not supported.
• Terminal: Ghostty, WezTerm, Kitty and iTerm2 are all great terminals that support most pls features.
• Nerd Fonts: Needed to render icons in the terminal.

Tip

Nerd Fonts are good for more than just pls. A number of CLI tools, like Starship and Powerlevel10k, recommend using Nerd Fonts.

Before picking a Nerd Font, check if your terminal app supports fallback fonts. If it does (most do), you can choose any monospaced font you like and set "Symbols Nerd Font" as the fallback to handle all the icons. If not, you can get patched versions of the most popular fonts from the Nerd Fonts website.

Additionally we recommend using a font that has programming ligatures, such as JetBrains Mono or Monaspace Neon (used in the examples on this site).

Installation

These are the different ways you can install pls on your machine.

Note

We are working on adding pls to more package managers like apt and dnf. If you add pls to a package manager or repository, please let us know!

Homebrew

pls is available to install for macOS and Linux via our official Homebrew tap. Currently pls is not available through Homebrew core, but it is planned for the future.

brew install pls-rs/pls/pls

This command will fetch and install the latest release of pls from GitHub.

Nix

pls is also available as a Nix package. You can install it using nix-env, add it to your NixOS configuration or just try it using nix-shell.

To permanently add pls to NixOS, update your config, usually located at /etc/nixos/configuration.nix.

environment.systemPackages = [
  pkgs.pls
];

Note

Thanks to TomaSajt for creating this package and to all its maintainers.

Caution

Since nixpkgs is a massive centralised repository, pls obtained from there might be out of date.

PyPI

pls is published as Python binary wheel to PyPI, so you can install it using uv (recommended) or pipx:

uv tool install pls --prerelease allow

You can suffix @<version> to the package name to install a specific version. The current latest version is vx.y.z. Or you can suffix @latest to get the latest at the time of installation.

Build from source

If you have the Rust toolchain and a C compiler installed on your computer, you can build from source locally for your operating system and architecture (libgit2 is vendored and compiled during the build). Also, we welcome your contributions!

cargo install --git https://github.com/pls-rs/pls

You can use --tag to install a specific version. The current latest version is vx.y.z. Or you can use --branch main to get the latest, unreleased version.

Binstall

pls complies with Binstall's requirements so you can use it to download pre-built binaries from releases on GitHub.

cargo binstall --git https://github.com/pls-rs/pls pls

You can use --version to install a specific version. The current latest version is vx.y.z.

Download binary

The CI + CD job compiles binaries for each supported OS on every code push. Additionally, we also cut periodic releases from the main branch of the repository. You can download the binary for your operating system and architecture by following these steps.

Tip

Eget downloads and extracts pre-built binaries from releases on GitHub. pls complies with Eget's requirements so you can replace steps 1 through 3 below with this one command. If you've configured Eget to use a target that's already on your $PATH, you can also skip step 4.

eget --pre-release pls-rs/pls

1. Download the binary file. You can either download the binary associated with a release or a commit.

   • Release

     1. Go to the GitHub Releases page for pls.
     2. Find the latest release i.e. vx.y.z.
     3. Expand the "Assets" attached to the release.

   • Commit

     1. Visit the page for pls's CI + CD workflow.
     2. Click on the last successful workflow.
     3. Scroll down to the "Artifacts" section.

2. Download the binary as per your operating system.

   • pls-aarch64-apple-darwin for macOS (Apple Silicon)
   • pls-x86_64-apple-darwin for macOS (Intel)
   • pls-x86_64-unknown-linux-musl for Linux (x86_64 e.g. Intel, AMD)
   • pls-aarch64-unknown-linux-musl for Linux (arm64)

3. Unzip the archive and find the single pls executable.

4. Place the executable on your $PATH. To do this, you can either add the directory that contains it to the path, or move/symlink the binary to a directory that is already on your $PATH.

Verification

You can check if pls was installed correctly and present on your $PATH by running the following command. If you see a version number, you're good to go!

pls --version # or -V

pls x.y.z

Usage

To run pls, type the following command into any terminal.

pls

By default, pls lists the contents of the current working directory, but you can pass any number of different files or directories as positional arguments.

If a directory path is passed, all the files and directories within that directory are listed. This is useful to see what's in the folder. If a file path is passed, only the file itself is listed. On its own, that's not very useful except to see if that file exists. But with the --det/-d flag, pls can display quite a lot of metadata for the file.

Help

To see what pls is capable of, and how to use those features, check out the built-in help. You can see the detailed help or a quick reference using the --help/-h flags respectively.

pls --help # or -h

pls is a prettier and powerful ls(1) for the pros.
 
Usage: pls [OPTIONS] [PATHS]...
...