pls on PyPI Python versions GPL-3.0

Demo of `pls`

pls is a better ls for developers. The “p” stands for “pro” (as in “professional”/”programmer”) or “prettier”, whichever helps you remember the command name.

It works in a manner similar to ls, in that it lists directories and files in a given directory, but it adds many more developer-friendly features.

Note that pls is not a replacement for ls. ls is a tried, tested and trusted command with lots of features. pls, on the other hand, is a simple tool for people who just want to see the contents of their directories.


pls provides many features over ls command. pls can:

  • show Nerd Font icons or emoji next to files and directories making it easier to read the output
  • colour output to elevate important files or dim unimportant ones
  • use a more nuanced approach to hidden files than plainly hiding files with a leading dot .
  • group directories and shows them all before files
  • ignore leading dots . and normalise case when sorting files
  • align files names by first character
  • cascade formatting rule specs by based on specificity levels
  • read .pls.yml files from the directory to augment its configuration
  • show more details like permissions, owner and size in columns
  • run quite fast, thanks to multiprocessing

The icon, color and most behaviour in the application can be configured using plain-text YAML files for the pros who prefer to tweak their tools.

Upcoming features

In the future pls will be able to

  • generate visibility rules by parsing .gitignore
  • add MIME type as another method for matching files to specs
  • use complete path based matching for files
  • link files and hide derived files behind the main ones
  • generate tree-like output for subdirectories

If you want to help implement any of these features, feel free to submit a PR. pls is free and open-source software.

Comparison with similar tools

There are a lot of ls replacements. Here are some of the most popular ones.

pls aims to stand out because of some very specific choices.

  • Does not intend to replace ls. pls, as a command, is just as easy to type.
  • Targets a more tech-savvy audience in its features.
  • Intelligently maps file type. Just comparing the file extension would be too generic.
  • Meticulously chosen iconography for the appreciating eyes.
  • Highly customisable at a project level using a simple .pls.yml file.
  • Built in a friendly language, Python. This makes it easy to fork and change it yourself.


To get the best of pls, install a Nerd Font on your computer. Nerd Fonts come patched with many icons from different popular icon sets. If you’re a “pro” (the target audience for pls) these fonts are basically a must.

pls is a pure-Python codebase and is deployed to PyPI. So installing it on any system with a supported Python version is quite straightforward.

$ python3 -m pip install --user pls

There are no native packages yet.


pls has a very simple API with easy to memorise flags. There are no mandatory arguments. Just run pls anywhere on your disk.

$ pls

There are a few optional arguments and flags you can use to tweak the behaviour. You can see the complete list of arguments and their description by passing the --help or -h flags.

$ pls --help


The only positional argument is a directory. Pass this to see the contents of a different folder rather than the current working directory.

$ pls path/to/somewhere/else


pls supports many icons for popular languages out of the box and will show icons by default. If you don’t have a Nerd Font (why?), you can switch to emoji icons using --icons emoji or -iemoji. Be warned they are quite bad. If you are a sad person, you turn icons off using --icon none or -inone.

Note: The built-in icon configuration is intentionally lean. The whole idea is for pls to be customisable by you.


You can choose to hide files or folders from the output using --no-files and --no-dirs respectively. Passing both will lead to a blank output. On the other hand if you want to see files and directories that pls would not show otherwise, pass --all.


By default pls will place all directories first, followed by files with both sorted alphabetically from A to Z. You can prevent folders from being first by passing the --no-dirs-first flag. You can change the sort to go from Z to A using --sort desc or -sdesc. Leading dots are ignored during sorting.


A lot of code related files start with a leading dot . for no valid reason. pls by default

  • moves their name left by one character to line up the actual alphabets
  • dims their leading dot

If you don’t like this, you can set --no-align to turn off all this behaviour in one swoop.


When you need more infomation about your files, pass the --details flag. This expands the list into a table, with

  • permissions
  • owner name
  • size

added to the output. The permissions are presented as rwx triplets. The size is presented in binary compound-units (the ones with the “i” like “*iB”). You can switch to decimal units by passing --units decimal or -udecimal. This flag has no effect unless the --detail flag is passed too.


View Github