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

> Install user-scanner on Linux macOS Windows Termux via pip in a virtual environment or using Nix for reproducible sandboxing. Get started easily today.

- Repository: [Kaif/user-scanner](https://github.com/kaifcodec/user-scanner)
- Tags: how-to-guide
- Published: 2026-08-30

---

**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:

```bash
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`](https://github.com/kaifcodec/user-scanner/blob/main/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:

```bash
pip install "user-scanner[mcp]"

```

According to the [`pyproject.toml`](https://github.com/kaifcodec/user-scanner/blob/main/pyproject.toml) configuration, this extra pulls in additional dependencies required by [`user_scanner/mcp/__init__.py`](https://github.com/kaifcodec/user-scanner/blob/main/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:

```bash
python3 -m venv .venv

# On Unix/macOS

source .venv/bin/activate

# On Windows PowerShell

.venv\Scripts\Activate.ps1

```

Once activated, install the package:

```bash
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:

```bash
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:

```bash
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:

```bash
user-scanner --help
user-scanner-mcp --help

```

Successful execution confirms that [`user_scanner/__main__.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/__main__.py) is properly configured as the entry point for the main CLI, while [`user_scanner/mcp/__init__.py`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/__main__.py), while `user-scanner-mcp` is an optional entry point provided by [`user_scanner/mcp/__init__.py`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/README.md).