Install NotPixel

Choose direct installation with configuration in your code, or the optional installation assistant. Both paths support new and existing accounts and the same local/remote processing options. Run setup inside your existing application.

Direct SDK installation

Install the packages, use your publisher ID, and configure the client in your code. Package installation does not ask questions or require CLI login. Obtain your publisher ID from your NotPixel account; publisher approval is required to serve ads with either installation path.

Local processing is included by default. Install a single package:

For JavaScript packages, you can also use pnpm add, yarn add or bun add with the same package names. For Expo, use its compatible installer:

# Local processing
npx expo install @notpixel/react-native @notpixel/react-native-embedding-local
 
# Or remote processing
npx expo install @notpixel/react-native

Configure local processing

Import the local JavaScript client and supply your publisher ID:

import Ads from 'notpixel';
 
const ads = new Ads({ publisherId: 'YOUR_PUBLISHER_ID' });
const ad = await ads.getAd({ input: 'How can I optimize PostgreSQL?' });

React Native uses the same constructor with an import from @notpixel/react-native/local. Its local addon requires a native rebuild; React Native CLI apps also run CocoaPods on iOS. Local native inference is unavailable in Expo Go.

Python includes local processing in its default installation:

from notpixel import Ads
 
ads = Ads(publisher_id="YOUR_PUBLISHER_ID")
ad = ads.get_ad(input="How can I optimize PostgreSQL?")

Configure remote processing

Use the same installation and choose remote processing explicitly in your code:

import Ads from 'notpixel/remote';
 
const ads = new Ads({
  publisherId: 'YOUR_PUBLISHER_ID',
  embeddingMode: 'remote',
});

React Native uses the same options with an import from @notpixel/react-native. Python uses embedding_mode with either Ads or AsyncAds:

from notpixel.remote import Ads
 
ads = Ads(publisher_id="YOUR_PUBLISHER_ID", embedding_mode="remote")

Remote sends sanitized context to NotPixel and its Cloudflare inference infrastructure; it does not initialize or download a local model. No SDK automatically switches to remote when local components are missing or fail. When switching an existing local mobile app to remote, remove its local addon if no other integration uses it, update CocoaPods on iOS and rebuild to remove the native inference runtime.

Your LLM provider configuration remains under your control. Calls that only fetch ads do not require an LLM model or provider credentials.

Optional assisted installation

Use the assistant if you want help connecting your account, choosing local/remote processing and generating configuration. An existing account can use this path too. All terminal prompts are in English.

JavaScript, TypeScript and React Native

Choose one command for your package manager:

# npm
npx notpixel@latest install
 
# pnpm
pnpm --config.ignore-scripts=true dlx notpixel@latest install
 
# Yarn 2+
yarn dlx notpixel@latest install
 
# Bun
bunx notpixel@latest install

React Native and Expo projects are detected automatically. The assistant uses your project’s package manager; Expo projects use expo install.

Run the command from the application that will use NotPixel. In a monorepo, run it from the app’s directory, choose a package when prompted at the root, or pass a path directly, for example:

npx notpixel@latest install --project apps/chat

The assistant uses the selected project’s package manager, even when launched with npx. For pnpm dlx, the option above skips scripts in the temporary launcher. The project install uses the project’s own policy. When the package manager needs approval for pending SDK scripts, the assistant asks during setup. CI uses the existing policy and an explicit --project if the target would otherwise be ambiguous.

The assistant offers Log in or Create an account and opens your browser for authorization. After authorization, it asks:

Where should NotPixel process context for ad selection?
  In your environment (local) [default]
  On NotPixel infrastructure (remote)

For Node.js and Python, the same package includes local inference. Remote selection changes context processing without loading the local model. React Native retains its platform-specific native addon. The assistant generates notpixel.ts and notpixel.config.json with your publisher ID and selected processing mode. Import ads from the generated file. For Node.js apps, the assistant also adds a NotPixel section to the selected app’s AGENTS.md. It points coding agents to the Markdown documentation for the installed version, starting at node_modules/notpixel/dist/docs/index.md. With direct package installation, you can add the same guidance from the SDK README . Configure your chosen LLM provider separately as usual.

Python

Install the SDK and run the optional Python assistant:

python -m pip install notpixel
python -m notpixel install

Python does not require Node.js. The assistant uses the same account and context questions, installs notpixel only for local processing, and generates notpixel_client.py plus notpixel.config.json.

Repeat setup and account commands

The assistant’s init command can configure an existing project and install missing components when needed. For example, run npx notpixel@latest init or python -m notpixel init. Changed configuration is shown before replacement. Repeating setup preserves unrelated project files and dependencies.

Both CLIs support login, logout and whoami. CLI credentials are stored in your user configuration directory, outside the project. The SDK uses the publisher ID configured in your application and does not depend on these CLI credentials. An account awaiting publisher approval can finish setup, but cannot serve ads until approved.

For automated use of the assistant, pass --non-interactive, --embedding-mode and an authorized CLI session or NOTPIXEL_CLI_TOKEN. The Node CLI also accepts --sdk node|react-native|python. Never include an installer token in an application bundle. Ordinary CI installs from your lockfile and SDK runtime calls do not require running or logging into the assistant.