justpath

Just a simple utility to explore PATH environment variable on Windows, Linux and MacOS.

Workflow

justpath shows your PATH environment variable line by line with numbering, comments and highlighing and helps detecting invalid or duplicate directories on your PATH.

You can also create a modified version of PATH string and use it in your shell startup script or through an environment manager. Note that justpath itself cannot change your shell PATH.

Try quickly

Install (with pip or pipx):

pip install justpath

Try the following:

justpath --raw
justpath
justpath --count
justpath --invalid
justpath --duplicates
justpath --duplicates --follow-symlinks
justpath --correct --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¹:

justpath --sort

What are the paths that contain bin string?

justpath --includes bin

What are the paths that do not contain windows string?

justpath --excludes windows

Are there any directories in PATH that do not exist?

justpath --invalid

Are there any duplicate directories in PATH?

justpath --duplicates

Same, but resolving symbolic links:

justpath --duplicates --follow-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 --string

One-line alternatives for justpath commands where they exist:

justpath --shell-equivalents

Useful cases

1. Filter directory names

justpath allows to filter paths that must or must not include a certain string. Filtering is case insensitive, --includes windows and --includes Windows will produce the same result. --excludes flag will filter out the directories containing 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.

You may also add --follow-symlinks flag in order to resolve symbolic links when counting and purging duplicate directories.

4. Dump `PATH` as JSON

justpath can dump a list of paths from PATH to JSON. You may add --correct flag to list only correct paths.

justpath --correct --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 --string ouput flag.

λ justpath --correct --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 --json
{"total": 52, "invalid": 1, "duplicates": 16}

7. Follow symlinks when looking for duplicates

Often times symbolic links are added to PATH to point to a particular version of a package. You can discover more duplicate directories with --follow-symlinks flag.

$ justpath --duplicates --follow-symlinks --includes dotnet
 6 /home/codespace/.dotnet (resolves to /usr/local/dotnet/7.0.306, duplicates: 2)
32 /usr/local/dotnet/current (resolves to /usr/local/dotnet/7.0.306, duplicates: 2)

$ justpath --duplicates --follow-symlinks --includes java
10 /home/codespace/java/current/bin (resolves to /usr/local/sdkman/candidates/java/21.0.1-ms/bin, duplicates: 2)
19 /usr/local/sdkman/candidates/java/current/bin (resolves to /usr/local/sdkman/candidates/java/21.0.1-ms/bin, duplicates: 2)

Installation

Stable version

pip install justpath

or with pipx

pipx 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.

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 - ton 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.

Tip

justpath --shell-equivalents provides a reference about one line commands for several shells that do similar jobs as justpath itself.

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.

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. ↩

rpdelaney/justpath