epogrebnyak/justpath

Inspect and refine PATH environment variable on Windows, Linux and MacOS.

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.

Footnotes

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

justpath's Issues

consider --append --drop flags

Show and modify PATH variable.

Usage:
  pathit show [--sort] [--includes text] [--only-exist | --only-ghost] [--numbers]
  pathit add PATH
  pathit drop n [--yes]

Put up a CI pipeline

Does it have a Windows machine to test?

add count using symlinks to --count output

There is much more duplicate folders on path using the --follow-symlinks flag, let's produce an extra line in --count ouput.

Add PathVar.from_json()

Could be useful for testing

add badge for Python Bytes podcast

@mikeckennedy - how do you like the badge? Thinking of putting the badge into a readme.

add `learn` command

print links.md in hypretext

from rich import print
>>> print("Visit my [link=https://www.willmcgugan.com]blog[/link]!")

link to reddit post

https://www.reddit.com/r/Python/comments/1ac7fao/pathit_just_show_me_my_path_in_way_i_can_read_it/

shell equivalents for justpath commands

Justpath would print what shell command you can do instead.

Easy for simple commands, less obvious for bigger commamds. Also a lot of comments this is trivial in bash.

Maybe start with just one flag --shell and then add --bash, --zsh or --cmd

`sep()` can be replaced with `os.pathsep`

sep() can be replaced with os.pathsep

Python has you covered there. Cheers!

name conflict at PyPI

PyPI says 400 The name 'pathit' is too similar to an existing project, (but does not provide a way to check for alternative names), so the package is not uploaded to PyPI.

Possible solution: find a better name for command line script and package that woudl suit PyPI

deduplicate directories

These are the same folder, should keep just 14.

24 C:\WINDOWS
14 C:\Windows

Should this be --remove-duplicates flag?

Duplicates may also display in yellow - can change the row data structure as:

@dataclass
class Duplicate:
   count: int

@dataclass
class Row:
  i: int
  path: Path
  error: FileNotFound | NotADirectoryError | Duplicate | None = None

Missing ANSI Escape sequence to reset color after output?

Hey, nice program, really like it!

One thing I noticed with justpath (Running on Windows 10 / Latest Windows Terminal / Latest PowerShell), not sure if this is platform specific:

The PS C:\ which is displayed as the internal prompt function of PowerShell still has the same foreground color as the output generated by justpath..

feature: check if current directory is on the path

What should the syntax be?

justpath --contains . 

What should the behavior be?

• sys.exit(0) if true
• sys.exit(1) if not true

Any messages to be printed?

Should resolve to real paths before checking?

brew installable on macs

It would be nice to install justpath using homebrew

brew install justpath

Thanks!

add Limitations section to docs

• will not resolve * or regex in path
• non-latin characters may require changing of PYTHONENCODING on Windows

`show --json` may deviate from `show`

I installed justpath in a Python 3.12.1 virtual environment. I usually look at a new app's help message:

> justpath --help
Traceback (most recent call last):

  File "<frozen runpy>", line 198, in _run_module_as_main

  File "<frozen runpy>", line 88, in _run_code

  File "D:\Users\user\dir\venv\Scripts\justpath.exe\__main__.py", line 7, in <module>
    sys.exit(typer_app())
             ^^^^^^^^^^^

RuntimeError: Type not yet supported: str | None

Running justpath gives the same error.

separate data model from presentation

Directory (original, resolved after symlink, and abspath) + Status(not a directory, dies not exist)

Count works on top of Directory + Status

Should make JSON dump of a data structure

~ may not expand properly

Possibly due to conda. Maybe need to call expanduser() before resolve().

Package not found on conda

Hi there,

I tried to install the package in different conda environments, first in the one with py==3.9.15 and another one with py==3.11.0.

However both environments failed to find the package.

I am using miniforge package manager by the way.

Does anyone know about the incident? Thanks!

--exclude is not used for --count

There are a few directories inserted by macOS that I cannot control. But they also do not exist. I'd like to be able to write commands like:

justpath --exclude somedir --count

But --count reports 3 missing directories, even though those directories contain somedir text.

Thanks for the cool util.

monday thoughts

A few thoughts:

• Sometimes paths can contain env variables. You might want to expand them, including expanduser

• Do you want to handle relative paths? This isn’t generally a good idea for the PATH variable, but it could be a decent exercise.

• It would be worthwhile to test your package on Linux, especially since WSL is so easy to get up. Linux file systems generally don’t care about casing, so if you want to support it, then you’ll also want to handle that.

https://www.reddit.com/r/Python/comments/1ac7fao/comment/kjtuk6f/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button

`--string --correct` breaks `archlinux-java` when setting PATH

archlinux-java is used to switch java versions by changing the directory that /usr/lib/jvm/default points to. --string --correct follows symbolic links so that export PATH=$(justpath --string --correct) might not use the current java version depending on how archlinux-java and setting PATH using justpath --string--correct are intermixed. justpath --string --purge-invalid doesn't follow symbolic links and so allows archlinux-java to continue to switch java versions.

I don't know if following symbolic links is the only difference between --correct and --purge-invalid.

­---Vladimir
P.S. Thanks for a great utility!

--tui add experimental text user interface

Maybe trogon or similar

split --bare into two flags

--numbers or --no-numbers
--comment or --no-comment

--bare itself can be three flags - no numbers, no-comment and no-color