Installing a command-line tool is usually a short process: download the correct build, place the executable in a known folder, add that folder to PATH, and test it in a new terminal. This checklist explains that workflow for Windows, macOS, and Linux, including portable binaries, package managers, permissions, architecture mismatches, shell profiles, and the most common reasons a terminal reports that a command cannot be found.
Overview
A command-line tool is an executable that runs from a terminal rather than through a graphical installer. Examples include developer utilities, media converters, file inspection tools, version-control helpers, and other web and workflow utilities. Some arrive as an installer, while others are distributed as a compressed archive containing one binary. The installation method affects where the files belong, but the central requirement is the same: your shell must be able to locate the executable.
PATH is an environment variable containing a list of folders. When you type a command without its full path, the shell searches those folders in order. If the tool is installed correctly but its folder is absent from PATH, the terminal may return “command not found,” “not recognized as an internal or external command,” or a similar message.
Before downloading, use the project’s official download page or a trusted release page. Select the file that matches the operating system and processor architecture. On release pages, names often distinguish Windows, macOS, and Linux builds, as well as x64, ARM64, or other architectures. The GitHub Releases download guide provides a useful way to interpret common release-file names. If a checksum is published, compare it before extracting or running the file; see the SHA-256 verification guide for platform-specific commands.
Checklist by scenario
Windows: installer or standalone executable
- Download the Windows installer or archive from the official source. Keep the original file until you have confirmed that the tool works.
- If it is an installer, review the destination folder and look for an option such as “Add to PATH.” Enable it only when you understand what the installer will change.
- If it is a ZIP archive, extract the executable to a stable location such as
C:\Tools\tool-nameor another folder intended for command-line utilities. Avoid leaving it in Downloads, because that folder is often cleaned or reorganized. - To add the folder manually, open Windows search and look for “environment variables.” Edit the user-level
Pathvariable if the tool is needed only for your account. Add the folder containing the executable, not the ZIP file and not a parent folder that does not contain it. - Close existing Command Prompt, PowerShell, or Windows Terminal windows. Open a new one so it receives the updated environment.
- Test the command with its version or help option, for example
tool-name --versionortool-name --help. To identify the executable being used, runwhere tool-name.
If Windows blocks an unfamiliar downloaded executable, do not bypass the warning automatically. Confirm the download source, checksum, and digital signature where available. A portable download can be convenient, but it still requires the same care as an installed application; the portable-versus-installed guide explains the trade-offs.
macOS: package manager, installer, or extracted binary
- Choose a build for the Mac’s processor architecture. A universal build may support more than one architecture; otherwise, choose the matching Intel or Apple silicon file when the project provides separate downloads.
- For a package manager installation, follow the project’s current instructions and note the reported install location. Package managers commonly manage
PATHfor you, but a shell configuration may still need updating. - For a compressed archive, extract the binary to a stable directory such as
~/binfor your user account or a system-wide location intended for command-line programs. Make sure the file is executable. - For a user-level
~/bindirectory, add it to the profile used by your shell. For a typical Zsh setup, that may be~/.zshrc; Bash users may use~/.bashrcor another profile file depending on how the shell starts. - Reload the profile with the appropriate command, or open a new terminal. Then run
command -v tool-nameandtool-name --version.
macOS may apply security controls to software downloaded from the internet. If an executable is rejected, first verify that it came from the intended source and that its checksum or signature matches. Do not treat a security prompt as a reason to use an unverified mirror.
Linux: package, archive, or user-local install
- Prefer the distribution’s package method when it provides the required version and functionality. Package-managed files can be easier to update and remove.
- For an official archive, extract it into a deliberate location. A user-local directory such as
~/.local/binavoids changing system files; a system-wide location may require administrator access and should follow local administration practices. - Ensure the executable permission is present. From the directory containing the file, a command such as
chmod +x tool-namemay be appropriate for a binary that is meant to run directly. - Add the chosen directory to
PATHin the shell’s startup file. For example, a user-local setup may useexport PATH="$HOME/.local/bin:$PATH". Place the change in the profile used by the shell you actually run. - Reload the profile or start a new terminal. Check the location with
command -v tool-name, then run the tool’s version or help command.
Keep distribution packages and manually extracted binaries from silently competing with each other. If both exist, the first matching folder in PATH determines which one runs.
What to double-check
- Architecture: Confirm that the download matches the operating system and processor. A wrong-architecture error is different from a missing
PATHentry. - Executable location: Check that the folder in
PATHcontains the executable itself. On Windows, verify the expected.exefile; on Unix-like systems, verify the file name and executable permission. - Current environment: A terminal opened before a
PATHchange may retain the old value. Test in a new window or reload the correct shell profile. - Shell syntax: Windows PowerShell, Command Prompt, Zsh, Bash, and other shells use different commands and profile files. A line copied from one shell may not work in another.
- Precedence: Use
whereon Windows orcommand -von macOS and Linux to find the selected executable. Multiple versions can produce confusing results. - Trust signals: Prefer an official download link, a documented mirror, and a published SHA-256 checksum or signature. The safe software download checklist covers these checks before installation.
When testing, start with a harmless command such as --version or --help. This confirms that the shell found the intended program without immediately processing files or changing a project.
Common mistakes
| Symptom | Likely cause | Practical check |
|---|---|---|
| “Command not found” or “not recognized” | The executable’s folder is not in PATH, or the terminal has not been restarted. | Inspect PATH, open a new terminal, and run where or command -v. |
| Access denied or permission denied | The file lacks execute permission, or the installation location requires elevated access. | Check permissions and choose a user-writable directory when a system-wide install is unnecessary. |
| Wrong architecture or cannot execute | The download does not match the operating system or processor. | Return to the official release page and select the correct build. |
| The old version still runs | An earlier copy appears first in PATH. | List all matches, remove or reorder obsolete entries, and test again. |
| Profile changes do nothing | The edit was made to a different shell’s startup file, or the line contains a syntax error. | Identify the active shell, inspect the relevant profile, and start a clean session. |
Another frequent mistake is adding a compressed archive, installer, or project directory to PATH instead of the directory containing the runnable file. Extract first, then add the exact binary directory. Avoid adding broad folders unnecessarily, since a shorter and more deliberate PATH is easier to audit.
When to revisit
Return to this checklist whenever you install a new CLI utility, move an executable, replace a computer, change shells, or upgrade an operating system. Revisit it before a project handoff or seasonal planning cycle if your workflow depends on scripts, automated media processing, deployment tools, or repeatable local environments. Tool releases can also change archive names, supported architectures, default installation paths, or package instructions, so use the project’s current documentation rather than copying an old command blindly.
- Record the tool name, version, source URL, installation method, and final path.
- Verify the download before running it, using a checksum or signature when the publisher provides one.
- Confirm that the selected architecture matches the machine.
- Check the executable location and
PATHin a fresh terminal. - Run the version or help command, then test the tool on a noncritical file or project.
- Remove obsolete versions only after confirming which scripts and users depend on them.
Keeping this small record turns a one-time install into a repeatable process. For broader download decisions, compare the platform-specific verification guidance and developer utility recommendations in the developer tools download guide.
