{"id":1036,"library":"userpath","title":"userpath","description":"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.","status":"active","version":"1.9.2","language":"python","source_language":"en","source_url":"https://github.com/ofek/userpath","tags":["path","environment variables","cross-platform","system","cli"],"install":[{"cmd":"pip install userpath","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required on Linux systems to identify distribution information for PATH modification.","package":"distro","optional":true}],"imports":[{"symbol":"userpath","correct":"import userpath"}],"quickstart":{"code":"import userpath\nimport os\n\n# Define a hypothetical directory to add to PATH\nlocation_to_add = os.path.expanduser('~/.local/bin/my_custom_tool')\n\nprint(f\"Checking if '{location_to_add}' is in current shell's PATH...\")\nif userpath.in_current_path(location_to_add):\n    print(f\"'{location_to_add}' is already in the current PATH.\")\nelse:\n    print(f\"'{location_to_add}' is NOT in the current PATH.\")\n\nprint(f\"Checking if '{location_to_add}' is in the user's persisted PATH settings...\")\nif not userpath.in_new_path(location_to_add):\n    print(f\"Appending '{location_to_add}' to user PATH...\")\n    userpath.append(location_to_add)\n    print(f\"'{location_to_add}' has been added to user PATH settings.\")\n    if userpath.need_shell_restart(location_to_add):\n        print(\"A new shell or system restart might be required for changes to take full effect.\")\nelse:\n    print(f\"'{location_to_add}' is already configured in the user's PATH settings.\")\n\n# To remove a path:\n# userpath.remove(location_to_add)","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to 3.7 or newer, or pin `userpath<1.8.0`.","message":"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).","severity":"breaking","affected_versions":">=1.8.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"1.9.0, 1.9.1, and potentially future versions"},{"fix":"Always restart any affected applications or open a new shell after `userpath` modifies the PATH to ensure the changes are picked up.","message":"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.","severity":"gotcha","affected_versions":">=1.8.0"},{"fix":"Ensure `bash` is installed in your Linux environment when using `userpath`, or consider using a base image that includes `bash`.","message":"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`.","severity":"breaking","affected_versions":"All versions on minimal Linux distributions where bash is not default or installed"}],"env_vars":null,"last_verified":"2026-05-12T22:55:19.522Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"pip install userpath","cause":"The 'userpath' package has not been installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'userpath'"},{"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.","cause":"The 'userpath' command-line utility's executable script is not in your system's PATH environment variable, or it was not properly installed.","error":"userpath: command not found"},{"fix":"Call `userpath.append()` separately for each individual path you want to add.","cause":"The 'userpath.append()' method is designed to add only one path string at a time, besides the optional 'requires_shell_restart' boolean argument.","error":"TypeError: append() takes 2 positional arguments but 3 were given"},{"fix":"Use `userpath.append(<path>)` or `userpath.prepend(<path>)` to add a path.","cause":"The 'userpath' module does not have a method named 'add'; paths are added using 'userpath.append()' or 'userpath.prepend()'.","error":"AttributeError: module 'userpath' has no attribute 'add'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.9.2","cli_name":"userpath","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.3,"disk_size":"18.6M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.3,"disk_size":"18.6M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.7,"import_time_s":0.02,"mem_mb":1.3,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.3,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.3,"disk_size":"20.6M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.3,"disk_size":"20.6M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":0.03,"mem_mb":1.3,"disk_size":"21M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.3,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1,"disk_size":"12.5M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1,"disk_size":"12.5M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.02,"mem_mb":1,"disk_size":"13M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1,"disk_size":"13M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.2,"disk_size":"12.2M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.2,"disk_size":"12.1M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.02,"mem_mb":1,"disk_size":"13M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1,"disk_size":"13M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.3,"disk_size":"18.1M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.3,"disk_size":"18.1M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2,"import_time_s":0.02,"mem_mb":1.3,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.3,"disk_size":"19M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":0}]}}