Install NNI v3.0 for Neural Architecture Search

Hand-designing every layer stack still burns days. Neural architecture search pushes that grind onto a searcher. Teams still grab Microsoft’s NNI (Neural Network Intelligence) when they need multi-trial or one-shot NAS, HPO, and compression behind one CLI – and the last official drop is v3.0.

This guide gets v3.0 installed and verified so you can start a NAS experiment today. The GitHub repo went read-only in September 2024, so pin 3.0 on purpose and treat it as frozen upstream.

System requirements for NNI v3.0

Per the official installation guide (as documented for the stable line), you need Python ≥ 3.7. Tested platforms: Ubuntu ≥ 18.04, Windows 10 ≥ 21H2, macOS ≥ 11.

Legacy Linux/Mac pages floated ~4-6 GB RAM and “tens of GB” disk as ballparks. As of those older notes, small multi-trial runs still fit; fat search spaces balloon under ~/nni-experiments fast – budget disk like you mean it.

Think of NNI less like a single library import and more like a small control plane: Python trials, a manager process, and a WebUI. That split is why PATH and Node/TS build junk show up during install even when your model code is fine.

Official download sources

PyPI still lists nni 3.0 as the latest stable (release dated Sep 14, 2023 on the project page / GitHub tag v3.0) – wheels for Linux manylinux x86-64, macOS x86-64, Windows amd64.

• Source / issues (read-only): github.com/microsoft/nni
• Docs: nni.readthedocs.io installation
• Docker Hub: msranni/nni – docker pull msranni/nni

On x86-64, pip first. Docker when you want a pre-baked shell. Source only for ARM64 (Apple Silicon) or a local patch.

Install NNI v3.0 step by step

Isolate the env. Mixing system Python with NNI’s TypeScript manager bits? That’s how half the “random” import failures start.

# Linux/macOS
python3 -m venv ~/nni-env
source ~/nni-env/bin/activate
pip install -U pip setuptools wheel

# Windows (PowerShell)
python -m venv nni-env
.nni-envScriptsActivate.ps1
python -m pip install -U pip setuptools wheel

Pin the release:

pip install nni==3.0
# or simply
pip install nni

Already on an older copy?

pip install --upgrade nni

Extras only if you call them:

pip install nni[DNGO]
# or everything
pip install nni[all]

Ubuntu + SMAC still wants swig 3 (official install note):

sudo apt install swig3.0
sudo rm -f /usr/bin/swig
sudo ln -s swig3.0 /usr/bin/swig

Docker path:

docker pull msranni/nni
docker run -it --rm -p 8080:8080 msranni/nni bash
# inside: nnictl --version

The catch is ARM64 / Apple Silicon – pip wheels are x86-64 only, so the docs send you to source (experimental):

git clone https://github.com/microsoft/nni.git
cd nni
# optional: git checkout v3.0
pip install -U setuptools pip wheel
python setup.py develop # version shows as 999.dev0

Pro tip: After a failed source build, python setup.py clean before retrying. Stale TS + setuptools artifacts masquerade as mysterious import errors.

First-time configuration

Local mode needs no global config file. Default experiment dir is ~/nni-experiments; override with experimentWorkingDirectory in YAML or the Python Experiment API.

Smoke tests still need a DL framework. Install PyTorch + torchvision in the same env – the nnictl hello scaffold expects them.

pip install torch torchvision
nnictl hello # starter project in the current directory

Holding old Retiarii scripts? v3.0 moved NAS to nni.nas (ModelSpace, NasExperiment, …). nni.retiarii imports break until you migrate – start new search spaces on the current Hello NAS APIs.

Verify the install works

nnictl --version
# expect: 3.0 (or 999.dev0 for develop installs)

python -c "import nni; print(nni.__version__)"

Run hello (or any example config) and open the WebUI URL from the terminal – usually http://127.0.0.1:8080. Stop with nnictl stop <experiment_id> or nnictl stop --all.

Turns out on Linux without Conda, nnictl often lands in ~/.local/bin and never hits PATH:

echo 'export PATH=${PATH}:${HOME}/.local/bin' >> ~/.bashrc
source ~/.bashrc

Common install errors and fixes

• bash: nnictl: command not found – add ~/.local/bin (snippet above), then open a new shell.
• No matching distribution on Apple Silicon – no ARM wheels. Build from source or use x86_64 Python under Rosetta. Pure pip install nni fails on M1/M2 until you compile.
• nni[SMAC] / ConfigSpace build errors – swig3 symlink as shown; some community threads also pin an older Cython before the extra. Install only extras you call.
• Cannot resume old experiment after upgrade – v3.0 release notes: cannot resume v2.x experiments (training-service break). Export what you need, start fresh on 3.0.
• WebUI connection drops / “Network Error” – check firewall, try another port (nnictl create --port 8088 ...), read ~/nni-experiments/<id>/log/nnimanager.log.
• ImportError for nni.retiarii – expected on v3. Move to nni.nas.

Reality: microsoft/nni is archived (Sep 18, 2024). No official fixes after v3.0. Freeze the env; watch transitive deps yourself – or plan a fork.

Upgrade and uninstall

Upgrade from 2.x:

pip install --upgrade nni==3.0
nnictl --version

Do not expect nnictl resume on a v2 experiment. Copy trial code and search spaces by hand.

Uninstall / cleanup:

pip uninstall nni
nnictl experiment delete --all # if nnictl still on PATH
rm -rf ~/nni-experiments # optional wipe of logs/results

Develop installs: pip uninstall nni, then delete the clone. Docker: remove container/image.

A frozen AutoML stack sounds awkward until you remember most production search pipelines already pin versions for reproducibility. NNI v3.0 fits that habit – just without a future upstream changelog.

FAQ

Is NNI still maintained after the archive?

No. v3.0 on PyPI is the last official release. Freeze it or fork.

Pip or Docker for a first neural architecture search setup?

Pip in a venv wins for daily coding and a host WebUI. Docker helps when swig/Node fights eat the afternoon. The Hub image is hefty (size may have changed; historically multi-GB) and has not tracked new upstream tags since the archive – fine for a smoke test, weak as a long-term dev home.

Can I run NAS without a GPU right after install?

Yes for tiny multi-trial jobs and nnictl hello. Throughput will crawl. Only raise trialGpuNumber / useActiveGpu when NVIDIA drivers and CUDA match your PyTorch build; otherwise keep GPU count at 0 and concurrency modest so CPU RAM does not thrash mid-search.

Next: activate the env, pip install nni==3.0, nnictl --version, then nnictl hello and open the WebUI. Jump to the official Hello NAS tutorial under nni.nas and wire your own model space.