Installation

This guide covers everything you need to install and set up ncprof, including prerequisites, the VS Code extension, and the ncompass SDK.

Prerequisites

Before installing ncprof, ensure you have the following:

Docker & Docker Compose

The profiling backend runs as Docker containers, so Docker is required. Check if Docker is installed:

docker --version
docker compose version

Installation:

• Windows/macOS: Docker Desktop 
• Linux: Official docs 

VS Code 1.80.0+

Check your VS Code version:

• Open VS Code
• Go to Help → About
• Ensure version is 1.80.0 or higher

If needed, download the latest version from code.visualstudio.com .

Installing the VS Code Extension

Install from VSCode Marketplace

The easiest way to install the extension is directly from the VSCode Marketplace:

1. Open VS Code
2. Go to the Extensions view (Ctrl+Shift+X or Cmd+Shift+X)
3. Search for “nCompass” or “ncprof” in the Extensions search bar
4. Click Install on the “nCompass Performance Optimization IDE” extension

Alternatively, you can install directly from the VSCode Marketplace .

Initial Setup Prompts

On startup, the extension will prompt for 2 details:

• User Email - We don’t collect any trace or code data, but we do record tool crash logs along side the user email to aid us with fixing bugs.
• Trace Directory - This is a path on your local system which you are currently storing traces or plan on storing traces to. This is so that the tool knows where to look for traces to analyze.

Verify Extension Installation

1. Open VS Code
2. Go to the Extensions view (Ctrl+Shift+X or Cmd+Shift+X)
3. Search for “ncprof” or “NCProf GPU Trace Viewer”
4. You should see the extension listed as installed

Installation Video Guide

Watch our Installation Guide  for a step-by-step walkthrough.

For example code showing how to generate trace files, check out our examples repository .

Installing the ncompass SDK

The ncompass SDK is the Python library that instruments your code based on ncprof’s configuration.

Install via pip

pip install ncompass

Verify Installation

python -c "import ncompass; print(f'ncompass version: {ncompass.__version__}')"

You should see the installed version number without any errors.

Initial Setup

First-Time Backend Launch

The first time you use ncprof, you need to start the profiling backend:

1. Open VS Code in your project workspace
2. Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)
3. Type “NCProf: Start Profiler Backend (Docker)”
4. Press Enter

The backend will:

• Create a .cache/ncompass directory in your workspace
• Pull the necessary Docker images (this may take a few minutes the first time)
• Start Redis and the profiling API server containers

You should see a success notification once the backend is running.

Configure Auto-Start (Optional)

To automatically start the backend when you open VS Code:

1. Open VS Code Settings (Ctrl+, or Cmd+,)
2. Search for “ncprof”
3. Enable ncprof.backend.autoStart

Or add to your settings.json:

{
  "ncprof.backend.autoStart": true
}

Verify Backend Status

Check that the backend is running correctly:

1. Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)
2. Type “NCProf: Check NCProf Backend Status”
3. Press Enter

You should see output in the terminal showing running containers.

Updating

Update the Extension

The extension will automatically update through VS Code’s extension marketplace. To manually check for updates:

1. Open Extensions view (Ctrl+Shift+X or Cmd+Shift+X)
2. Search for “nCompass” or “NCProf GPU Trace Viewer”
3. If an update is available, you’ll see an “Update” button
4. Click “Update” to install the latest version

Alternatively, you can visit the VSCode Marketplace  to see the latest version.

Update the ncompass SDK

pip install --upgrade ncompass

Uninstalling

Remove the Extension

1. Open Extensions view (Ctrl+Shift+X)
2. Find “NCProf GPU Trace Viewer”
3. Click Uninstall

Remove the ncompass SDK

pip uninstall ncompass

Remove Workspace Data

# Remove the cache directory
rm -rf .cache/ncompass

Next Steps

Now that you have ncprof installed:

• Quick Start: Complete the 5-minute getting started guide
• Detailed breakdown of profiling workflow: Learn the detailed profiling workflow
• Settings & Commands: Explore available configuration options