userpath

1.9.2 verified Tue May 12 auth: no python install: verified

userpath is a cross-platform Python tool designed to simplify the modification of a user's PATH environment variable without requiring elevated privileges. It provides a programmatic and command-line interface to append, prepend, or verify locations within the user's PATH. The library is actively maintained, with its latest version being 1.9.2, and has a consistent release cadence addressing bug fixes and feature enhancements.

pip install userpath

Common errors

error ModuleNotFoundError: No module named 'userpath' ↓

cause The 'userpath' package has not been installed in the current Python environment.

fix

pip install userpath

error userpath: command not found ↓

cause The 'userpath' command-line utility's executable script is not in your system's PATH environment variable, or it was not properly installed.

fix

Run python -m userpath append <path> to use the module directly, or ensure pip's script directory (where 'userpath' is installed) is included in your system's PATH.

error TypeError: append() takes 2 positional arguments but 3 were given ↓

cause The 'userpath.append()' method is designed to add only one path string at a time, besides the optional 'requires_shell_restart' boolean argument.

fix

Call userpath.append() separately for each individual path you want to add.

error AttributeError: module 'userpath' has no attribute 'add' ↓

cause The 'userpath' module does not have a method named 'add'; paths are added using 'userpath.append()' or 'userpath.prepend()'.

fix

Use userpath.append(<path>) or userpath.prepend(<path>) to add a path.

Warnings

breaking Support for Python 2.7 and Python 3.6 was dropped in version 1.8.0. Users running these Python versions must either upgrade their Python environment or use an older version of `userpath` (pre-1.8.0). ↓

fix Upgrade Python to 3.7 or newer, or pin `userpath<1.8.0`.

gotcha On non-Windows systems, `userpath`'s behavior regarding which shell configuration files are modified (e.g., only login shells) has fluctuated across recent minor versions (1.9.0 introduced, 1.9.1 temporarily reverted). This could lead to PATH changes not being universally applied across all shell types, requiring users to manually verify or adjust shell configurations. ↓

fix After modifying PATH on non-Windows, always verify the change across different shell types (e.g., login, interactive, non-interactive) and be aware that `userpath`'s target shell configuration files may change with updates.

gotcha After `userpath` modifies the user/system PATH, applications or shells that were already running (e.g., terminals, IDEs) may not immediately recognize the new `PATH` variable. A full restart of these applications, or opening a new shell, might be necessary. ↓

fix Always restart any affected applications or open a new shell after `userpath` modifies the PATH to ensure the changes are picked up.

breaking On some minimal Linux environments (e.g., Alpine Linux), `userpath` relies on `bash` to execute shell commands for PATH manipulation and checking. If `bash` is not installed, `userpath` operations will fail with a `FileNotFoundError`. ↓

fix Ensure `bash` is installed in your Linux environment when using `userpath`, or consider using a base image that includes `bash`.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.02s 18.6M

3.10 alpine (musl) - - 0.03s 18.6M

3.10 slim (glibc) wheel 1.7s 0.02s 19M

3.10 slim (glibc) - - 0.02s 19M

3.11 alpine (musl) wheel - 0.04s 20.6M

3.11 alpine (musl) - - 0.04s 20.6M

3.11 slim (glibc) wheel 1.8s 0.03s 21M

3.11 slim (glibc) - - 0.04s 21M

3.12 alpine (musl) wheel - 0.02s 12.5M

3.12 alpine (musl) - - 0.03s 12.5M

3.12 slim (glibc) wheel 1.6s 0.02s 13M

3.12 slim (glibc) - - 0.03s 13M

3.13 alpine (musl) wheel - 0.02s 12.2M

3.13 alpine (musl) - - 0.03s 12.1M

3.13 slim (glibc) wheel 1.6s 0.02s 13M

3.13 slim (glibc) - - 0.03s 13M

3.9 alpine (musl) wheel - 0.02s 18.1M

3.9 alpine (musl) - - 0.03s 18.1M

3.9 slim (glibc) wheel 2.0s 0.02s 19M

3.9 slim (glibc) - - 0.03s 19M

Imports

userpath
```
import userpath
```

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to check for, add, and verify a directory in the user's PATH. It also informs the user if a shell restart is necessary. The example uses a placeholder directory in the user's home directory.

import userpath
import os

# Define a hypothetical directory to add to PATH
location_to_add = os.path.expanduser('~/.local/bin/my_custom_tool')

print(f"Checking if '{location_to_add}' is in current shell's PATH...")
if userpath.in_current_path(location_to_add):
    print(f"'{location_to_add}' is already in the current PATH.")
else:
    print(f"'{location_to_add}' is NOT in the current PATH.")

print(f"Checking if '{location_to_add}' is in the user's persisted PATH settings...")
if not userpath.in_new_path(location_to_add):
    print(f"Appending '{location_to_add}' to user PATH...")
    userpath.append(location_to_add)
    print(f"'{location_to_add}' has been added to user PATH settings.")
    if userpath.need_shell_restart(location_to_add):
        print("A new shell or system restart might be required for changes to take full effect.")
else:
    print(f"'{location_to_add}' is already configured in the user's PATH settings.")

# To remove a path:
# userpath.remove(location_to_add)