Skip to content

pip Installation

Install Code Scalpel as a Python package for command-line use, scripting, or custom integrations.

Quick Install

pip install codescalpel

Verify the installation:

codescalpel --version
# Code Scalpel v1.4.0

Installation Options

Standard Installation

pip install codescalpel

With Development Dependencies

pip install codescalpel[dev]

Specific Version

pip install codescalpel==1.4.0

From Source

git clone https://github.com/your-org/code-scalpel.git
cd code-scalpel
pip install -e .

Using pipx (Isolated)

For a clean, isolated installation:

pipx install codescalpel

This installs Code Scalpel in its own virtual environment while making it available globally.

Command Line Usage

Basic Commands

# Show help
codescalpel --help

# Show version
codescalpel --version

# Run as MCP server (for AI assistants)
codescalpel

# Analyze a file
codescalpel analyze --file src/main.py

# Security scan
codescalpel security-scan --file src/auth.py

Output Formats

# JSON output (for scripting)
codescalpel analyze --file src/main.py --output json

# Pretty-printed output
codescalpel analyze --file src/main.py --output pretty

# Minimal output
codescalpel analyze --file src/main.py --output minimal

Python API Usage

Basic Import

from code_scalpel import analyze_code, security_scan

# Analyze code
result = analyze_code(
    file_path="src/main.py"
)

print(result.functions)  # List of functions
print(result.classes)    # List of classes
print(result.imports)    # List of imports

Security Scanning

from code_scalpel import security_scan

# Scan for vulnerabilities
vulnerabilities = security_scan(
    file_path="src/database.py"
)

for vuln in vulnerabilities:
    print(f"{vuln.severity}: {vuln.type} at line {vuln.line}")

Code Extraction

from code_scalpel import extract_code

# Extract a specific function
code = extract_code(
    file_path="src/utils.py",
    target_type="function",
    target_name="process_data"
)

print(code.source)  # The extracted code
print(code.line_start, code.line_end)  # Line range

Async API

All tools support async operation:

import asyncio
from code_scalpel import analyze_code_async

async def main():
    result = await analyze_code_async(
        file_path="src/main.py"
    )
    return result

result = asyncio.run(main())

Configuration

Environment Variables

# Set license path
export CODE_SCALPEL_LICENSE_PATH=/path/to/license.jwt

# Set config directory
export CODE_SCALPEL_CONFIG_PATH=/path/to/config

# Enable debug logging
export CODE_SCALPEL_DEBUG=1

Config File

Create .code-scalpel/config.json in your project:

{
  "default_output_format": "json",
  "timeout_seconds": 60,
  "max_file_size_mb": 10
}

Virtual Environment Setup

Recommended setup for projects:

# Create virtual environment
python -m venv .venv

# Activate (Linux/macOS)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

# Install Code Scalpel
pip install codescalpel

# Verify
codescalpel --version

Requirements File

Add to your requirements.txt:

codescalpel>=1.4.0

Or pyproject.toml:

[project]
dependencies = [
    "codescalpel>=1.4.0",
]

Integration Examples

Pre-Commit Hook

.pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: code-scalpel-security
        name: Code Scalpel Security Scan
        entry: codescalpel security-scan
        language: system
        files: \.py$

Makefile

Makefile
.PHONY: analyze security-scan

analyze:
    codescalpel analyze --file $(FILE) --output pretty

security-scan:
    codescalpel security-scan --project-root . --output json > security-report.json

Python Script

scripts/analyze_project.py
#!/usr/bin/env python
"""Analyze project and generate report."""

from code_scalpel import get_project_map, security_scan
import json

def main():
    # Get project structure
    project = get_project_map(project_root=".")

    # Find all Python files
    python_files = [f for f in project.files if f.endswith('.py')]

    # Scan each file
    all_vulnerabilities = []
    for file_path in python_files:
        vulns = security_scan(file_path=file_path)
        all_vulnerabilities.extend(vulns)

    # Generate report
    report = {
        "total_files": len(python_files),
        "vulnerabilities": len(all_vulnerabilities),
        "details": [v.to_dict() for v in all_vulnerabilities]
    }

    print(json.dumps(report, indent=2))

if __name__ == "__main__":
    main()

Troubleshooting

ModuleNotFoundError: No module named 'code_scalpel'
  1. Verify installation: pip show codescalpel
  2. Check you're in the correct virtual environment
  3. Try reinstalling: pip install --force-reinstall codescalpel
Command 'codescalpel' not found
  1. Check if installed: pip show codescalpel
  2. Find the install location: pip show -f codescalpel | grep bin
  3. Add the bin directory to your PATH
  4. Or use python -m code_scalpel instead
SSL certificate errors 
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org codescalpel
Conflicts with other packages

Use pipx for isolated installation: 

pip install pipx
pipx install codescalpel

Upgrading

# Upgrade to latest
pip install --upgrade codescalpel

# Upgrade to specific version
pip install codescalpel==1.4.0

Uninstalling

pip uninstall codescalpel

Next Steps