How to Troubleshoot 'graphify: command not found' After pip Installation

The 'graphify: command not found' error occurs when the console script installed by pip in your user-scripts directory (e.g., ~/.local/bin) is not included in your system's PATH environment variable.

The graphify CLI tool from the safishamsi/graphify repository defines its entry point in pyproject.toml as graphify = "graphify.__main__:main", yet installing via standard pip install graphifyy often fails to register the command because the executable wrapper is placed outside your shell's default PATH. This guide explains why this happens and how to fix it using the exact source file locations from the v8 release.

Why pip Installation Fails to Expose the graphify Command

When you run pip install graphifyy, pip creates an executable wrapper based on the console-script declaration in pyproject.toml. This wrapper calls the main() function defined in graphify/__main__.py. However, pip places this wrapper in your Python environment's user-scripts directory—typically ~/.local/bin on Linux, ~/Library/Python/3.x/bin on macOS, or %APPDATA%\Python\Python3x\Scripts on Windows. If this location is not in your PATH, your shell cannot locate the graphify binary.

Common Causes and Solutions

Missing User Scripts Directory in PATH

The most frequent cause is that pip's user installation directory is excluded from your shell's PATH environment variable.

Linux fix:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

macOS fix (Zsh):

echo 'export PATH="$HOME/Library/Python/3.10/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify the fix:

which graphify
graphify --version

Conflicting Python Environments

If multiple Python versions exist on your system, pip may install to one environment while your shell searches another.

Test this by running:

python -m graphify --version

If this succeeds but graphify alone fails, your PATH points to a different Python installation than where pip installed the package.

Windows PowerShell Path Syntax Errors

On Windows PowerShell, prefixing the command with a forward slash causes the shell to interpret it as a path separator rather than a command name.

Incorrect:

/graphify .

Correct:

graphify .

Recommended Installation Methods

The safishamsi/graphify repository recommends using uv or pipx instead of plain pip, as both tools automatically manage PATH entries and isolate dependencies.

Using uv (recommended):

uv tool install graphifyy

Using pipx:

pipx install graphifyy

Both methods create isolated environments and automatically place the graphify executable on your PATH, eliminating the "command not found" error.

Manual Workarounds for Existing Installations

If you must use an existing pip installation without modifying PATH, invoke the module directly:

python -m graphify --version

This bypasses the console script wrapper and executes graphify/__main__.py directly, calling the main() function without requiring the shell to locate the graphify executable.

Summary

• The graphify command is defined as a console-script entry point in pyproject.toml: graphify = "graphify.__main__:main"
• Standard pip installations place the executable in user-specific directories (Linux: ~/.local/bin, macOS: ~/Library/Python/3.x/bin) often excluded from PATH
• Best practice: Use uv tool install graphifyy or pipx install graphifyy for automatic PATH management
• Manual fix: Add your platform's user-scripts directory to PATH or use python -m graphify as a fallback
• Source verification: The CLI implementation resides in graphify/__main__.py at the v8 tag

Frequently Asked Questions

Why does python -m graphify work but the graphify command return "not found"?

This indicates the package is installed in your current Python environment, but the scripts directory containing the graphify executable is not in your system's PATH. The python -m syntax executes graphify/__main__.py directly, bypassing the need for the console script wrapper to be accessible via PATH.

Where is the graphify entry point defined in the source code?

The entry point is declared in pyproject.toml as graphify = "graphify.__main__:main", which references the main() function in graphify/__main__.py. This function implements the CLI interface that gets wrapped into the system executable when the package is installed.

Should I use pip, uv, or pipx to install graphify?

According to the repository documentation, uv and pipx are strongly recommended because they automatically handle PATH configuration and isolate dependencies. Plain pip requires manual PATH configuration on most systems, which commonly leads to the "command not found" error described in the troubleshooting guide.

How do I verify that graphify is correctly installed?

Run which graphify (Linux/macOS) or where graphify (Windows) to confirm the executable location. Then verify functionality with graphify --version. If these commands return the full path and version information, your installation and PATH configuration are correct according to the source implementation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}