justpath

I always get the feeling that nobody knows what a PATH is and at this point they are too afraid to ask. (reddit)

Explore PATH environment variable on Windows, Linux or Mac, detect and eliminate invalid or duplicate directories.

Quick start

Install with pip, pipx or uv, choose any command from below:

pip install justpath
pipx justpath
uv tool install justpath

Try the following:

justpath --raw
justpath
justpath --count
justpath --invalid
justpath --duplicates
justpath --duplicates --no-symlinks
justpath --correct
justpath --correct --format string

Screencast

Basic usage

What is the raw content of PATH string?

justpath --raw

List directories in PATH line by line.

justpath

Same as above, but no line numbers, no comments, no color, just bare text.

justpath --bare

Show directories from PATH in alphabetic order[^1]:

justpath --sort --no-symlinks

The result will look different when sorted by real paths:

justpath --sort --symlinks

[^1]: Sorting helps to view and analyze PATH. Do not put a sorted PATH back on your system as you will loose useful information about path resolution order.

What are the paths that contain bin string?

justpath --includes bin

What are the paths that do not contain windows string?

justpath --excludes windows

These flags can be repeated:

justpath --excludes bin --excludes codespace

May there be any directories in PATH that do not exist?

justpath --invalid

Are there any duplicate directories in PATH?

justpath --duplicates

See the same without resolving symlinks:

justpath --duplicates --no-symlinks

What is the PATH without invalid paths and duplicates?

justpath --purge-invalid --purge-duplicates

Same as above but more concise:

justpath --correct

A clean PATH string in OS-native format:

justpath --correct --format string

Useful cases

1. Filter directory names

justpath allows to filter paths that must or must not include a certain string. On Windows, filtering is effectively case insensitive, so --includes windows and --includes Windows usually produce the same result. --excludes filters out directories containing the provided string.

λ justpath --sort --includes windows --excludes system32
39 C:\Users\Евгений\AppData\Local\Microsoft\WindowsApps
24 C:\WINDOWS
14 C:\Windows
46 C:\tools\Cmder\vendor\git-for-windows\cmd
47 C:\tools\Cmder\vendor\git-for-windows\mingw64\bin
12 C:\tools\Cmder\vendor\git-for-windows\usr\bin

2. Directory does not exist or not a directory

justpath will indicate if path does not exist or path is not a directory.

Below is an example from Github Codespaces, for some reason /usr/local/sdkman/candidates/ant/current/bin does not exist, but included in PATH.

λ justpath --sort --includes sdkman
19 /usr/local/sdkman/bin
23 /usr/local/sdkman/candidates/ant/current/bin (directory does not exist)
21 /usr/local/sdkman/candidates/gradle/current/bin
20 /usr/local/sdkman/candidates/java/current/bin
22 /usr/local/sdkman/candidates/maven/current/bin

Added file touch d:\quarto\this_is_a_file for example below.

λ justpath --includes quarto
33 C:\Program Files\Quarto\bin
41 D:\Quarto\bin
50 x:\quarto\does_not_exist (directory does not exist)
51 d:\quarto\this_is_a_file (not a directory)

Use --invalid flag to explore what parts of PATH do not exist or not a directory.

λ justpath --includes quarto --invalid
50 x:\quarto\does_not_exist (directory does not exist)
51 d:\quarto\this_is_a_file (not a directory)

3. Purge incorrect paths

--correct flag will drop invalid paths from listing.

λ justpath --includes quarto --correct
33 C:\Program Files\Quarto\bin
41 D:\Quarto\bin

--correct flag is the same as applying both --purge-invalid and --purge-duplicates flag. The duplicates are purged from the end of a string.

4. Dump PATH as JSON

justpath can dump a list of paths from PATH to JSON.

justpath --format json

5. Create new content string for PATH

With justpath you can create new PATH contents and use it in your shell startup script. As any child process justpath itself cannot modify PATH in your current environment.

You can get a valid string for your PATH in a format native to your operating system using --format string ouput flag.

λ justpath --correct --format string
C:\tools\Cmder\bin;C:\tools\Cmder\vendor\bin;C:\Windows\system32;C:\Windows;...

6. Count directories in PATH

λ justpath --count
52 directories in your PATH
1 does not exist
16 duplicates

λ justpath --count --format json
{"total": 52, "invalid": 1, "duplicates": 16}

Installation

Stable version

pip install justpath

or with pipx

pipx install justpath

or uv:

uv tool install justpath

Development version

git clone https://github.com/epogrebnyak/justpath.git
cd justpath
pip install -e .

or shorter:

pip install git+https://github.com/epogrebnyak/justpath.git

Other package managers

Installation via conda or homebrew not yet supported.

CLI tool

After installation you can try the command line script:

justpath --help

Motivation

I think this quote about PATH is quite right:

I always get the feeling that nobody knows what a PATH is and at this point they are too afraid to ask.

PATH environment variable syntax on Windows and on Linux are different, so I wrote this utility to be able to explore PATH more easily.

My own use case for justpath was exploring and sanitizing the PATH on Windows together with Rapid Environment Editor. I also find it useful to inspect PATH on a remote enviroment like Codespaces to detect invalid paths.

Feedback

Some of positive feedback I got about the justpath package:

I like it! I do the steps involved in this occasionally, manually. It's not hard but this makes it nice. Not sure I'll use it since it is one more thing to install and remember, but the author had an itch and scratched it. Well done.

It's handy to see your path entries in a list. Checking whether each entry is a valid location is neat, too. But even better, from my perspective, you published the code and got feedback from people, including related implementations. That’s worth it, in my book. Edit: I like the includes part, too.

I think this is a cool package. Some of my first scripts in several languages have just been messing with file system abstractions. Files and file paths are much more complex than most people think.

Development notes

More about PATH

See links.md for more information about PATH. oneliners.md provides information about equivalent shell commands.

Making of command line interfaces (CLIs)

Few good links about CLI applications in general:

• docopt is a great package to develop intuition about command line interfaces.
• clig - lots of useful suggestions about CLIs including expected standard flags (--silent, --json, etc).
• 12 factor CLI app - cited by clig.

Alternatives

Linux scripting

On Linux you can run echo $PATH | tr ":" "\n" to view your path line by line and combine it with grep, sort, uniq and wc -l for the similar effect as justpath commands.

The benefit of a script is that you do not need to install any extra dependency. The drawback is that not everyone is good at writing bash scripts. Scripting would also be a bit more problematic on Windows.

Check out the discussion at Hacker News about bash and zsh scripts and justpath scenarios.

Other utilities

Even better tools than justpath may exist.

• Rapid Environment Editor for Windows is a gem (no affiliation).
• Maybe some smart command-line utility in Rust will emerge for PATH specifically, but not there yet.
• There is pathdebug written in Go that goes a step futher and attempts to trace where your PATH is defined.
• There is a family of tools to manage environment paths like dotenv or its Python port, and a newer tool called envio written in Rust.

Changelog

Future versions

• homebrew
• TUI
• repo section for PATH JSONs, better serialization
• just-style recipes with uv runner
• prek precommits

v0.1.4

• Explict MIT LICENCE file by [@thewchan][https://github.com/epogrebnyak/justpath/pull/34]

v0.1.3

• Always resolve symlinks and use real path to count duplicates.
• --no-symlinks will hide resolved paths from display.
• justpath --sort sorts by resolved paths, justpath --sort --no-symlinks sorts by raw paths.
• --format lines | string | json modifier.
• --includes and --excludes allow repetition (justpath --excludes bin --excludes codespace)
• --version flag.
• Dropped --shell-equivalents flag, created docs page.
• Switched uv package manager.
• Using rich for color output and a new color scheme.
• Should fix #28] escape char bug.
• Sister project in Rust: https://github.com/epogrebnyak/justpath.rs