How to Install user-scanner on Different Operating Systems: 3 Methods Explained

You can install user-scanner on Linux, macOS, Windows, or Termux using pip from PyPI, inside a virtual environment for isolation, or via Nix for reproducible sandboxing on Unix systems.

The user-scanner package from the kaifcodec/user-scanner repository provides a cross-platform Python CLI tool for scanning operations. Whether you need a quick global install or a reproducible development environment, the project supports Python 3.10+ and offers multiple installation paths tailored to different operating systems and isolation requirements.

Prerequisites

Before installing user-scanner, ensure your system meets the base requirement of Python 3.10 or higher. The package is distributed via PyPI and uses standard Python packaging tools, making it compatible with any platform that supports modern Python interpreters.

Method 1: Install via PyPI (Recommended for All Platforms)

The simplest and officially supported route uses pip to pull pre-built wheels from PyPI. This method works identically across Linux, macOS, Windows, and Termux environments.

Installing the Core Package

Upgrade pip to ensure compatibility, then install the base package:

python3 -m pip install --upgrade pip
pip install user-scanner

This command installs the core engine located in user_scanner/core/ and registers the user-scanner console-script entry point defined in user_scanner/__main__.py.

Installing with MCP Server Support

To enable the optional Model Context Protocol (MCP) server for AI agent integration, install the package with the [mcp] extra:

pip install "user-scanner[mcp]"

According to the pyproject.toml configuration, this extra pulls in additional dependencies required by user_scanner/mcp/__init__.py, which exposes the user-scanner-mcp CLI entry point.

Method 2: Virtual Environment Installation (Isolated Setup)

For isolated development environments that avoid polluting system packages, create a virtual environment before installing. This approach is recommended when running user-scanner alongside other Python projects with conflicting dependencies.

Create and activate a virtual environment:

python3 -m venv .venv

# On Unix/macOS

source .venv/bin/activate

# On Windows PowerShell

.venv\Scripts\Activate.ps1

Once activated, install the package:

pip install user-scanner

The virtual environment-local installation ensures the user-scanner and user-scanner-mcp commands are only available within the activated shell session.

Method 3: Nix Installation (Linux and macOS)

For power users on Linux or macOS who prefer reproducible, sandboxed environments without a global Python installation, the repository provides Nix flake support.

One-Off Execution

Run the tool immediately without permanent installation:

nix run github:kaifcodec/user-scanner/main -- --help

Interactive Shell Session

Drop into a temporary shell with user-scanner pre-installed and available on PATH:

nix shell github:kaifcodec/user-scanner/main

This method bypasses the need for pip entirely, leveraging the Nix package manager to handle the Python runtime and dependencies.

Verifying the Installation

Regardless of installation method, verify that the CLI entry points are correctly registered on your system PATH:

user-scanner --help
user-scanner-mcp --help

Successful execution confirms that user_scanner/__main__.py is properly configured as the entry point for the main CLI, while user_scanner/mcp/__init__.py handles the MCP server variant.

Summary

• PyPI installation works universally across all platforms and is the fastest way to get started, with optional [mcp] extras for AI integration.
• Virtual environments provide isolation from system Python packages and are ideal for development workflows.
• Nix offers reproducible, sandboxed execution on Linux and macOS without requiring a permanent local installation.
• All methods install the same core engine from user_scanner/core/ and make the user-scanner and user-scanner-mcp commands available.

Frequently Asked Questions

What Python version is required to run user-scanner?

User-scanner requires Python 3.10 or higher. This requirement is defined in the project's pyproject.toml metadata and enforced during installation.

Can I install user-scanner on Windows?

Yes. Windows is fully supported via the PyPI installation method using pip. The virtual environment activation command differs slightly (use .venv\Scripts\Activate.ps1 in PowerShell), but the installation process is otherwise identical to macOS and Linux.

What is the difference between user-scanner and user-scanner-mcp?

user-scanner is the core CLI entry point defined in user_scanner/__main__.py, while user-scanner-mcp is an optional entry point provided by user_scanner/mcp/__init__.py that implements the Model Context Protocol for AI agent integration. Install the [mcp] extra to enable the second command.

Where can I find usage examples after installation?

The repository includes a docs/USAGE.md file that demonstrates how to call the scanning engine programmatically from Python, complementing the CLI usage shown in the main README.md.

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