Troubleshooting
Use this page when nitid does not start, a command is missing, a model does not load, or Docker behaves differently than expected.
Most nitid problems come from one missing setup step. The usual flow is:
- You run a command.
- That command looks for the project environment or a model checkpoint.
- If one of those pieces is missing, Python prints an error.
- The fix is usually to install dependencies, download a model, or use the right command form.
nitid: command not found
What it means
The nitid command exists inside Nitid's virtual environment, but your terminal cannot see it directly.
This usually happens when .venv is not activated.
Fix
From the repository root, use uv run:
uv run nitid --help
uv run nitid predict --help
Or activate the environment first:
source .venv/bin/activate
nitid --help
Inside the Docker container, you can also call the executable directly:
.venv/bin/nitid --help
See the command-line guide for the full CLI workflow.
Installation fails with a new Python version
What it means
nitid currently supports Python >=3.10,<3.14.
PyTorch and torchvision wheels are not always available for every new Python version immediately. If your system uses a newer Python, such as 3.14, pip reports that no version of nitid matches, or dependency installation fails before nitid is even installed.
Fix
Use Python 3.10, 3.11, 3.12, or 3.13.
Then recreate the environment:
uv sync
For development tools:
uv sync --extra dev
On Apple Silicon Macs, use the Docker setup if native dependency installation is not suitable:
docker compose up -d
docker compose exec -it nitid-dev bash
uv sync --frozen --extra dev
See the macOS Docker setup for details.
Model download fails
What it means
When you use a supported model name like model1s, nitid
resolves the selected task, downloads the matching checkpoint when needed, and
prepares it for the integrated runtime.
The workflow is:
NITID("model1s", task="detect")
-> nitid checks the model registry
-> resolves weights for the selected task
-> downloads the official checkpoint when needed
-> builds the matching integrated model configuration
-> writes a local prepared checkpoint
If the internet connection or class names file is missing, the download or wrapping step can fail.
Fix
Try a direct download command:
uv run nitid download model=model1s task=detect
To save the model in a folder:
uv run nitid download model=model1s task=detect output=models
To replace an existing wrapped checkpoint:
uv run nitid download model=model1s task=detect output=models force=true
Detection, instance segmentation, and semantic segmentation all use the same
public model names (model1n, model1s, model1m, model1l,
model1x) with an explicit task=.... model1n is available only for
task=segment and task=semantic.
Checkpoint gives KeyError: 'config'
What it means
nitid expects a runtime checkpoint with embedded config and class names. Training runs save this format automatically.
Some external research checkpoints contain only weights. That is why nitid
cannot find config.
Fix
If you are using an official model, use the model name and let nitid prepare it:
from nitid import NITID
model = NITID("model1s", task="detect")
Or use the CLI:
uv run nitid download model=model1s task=detect
If you are maintaining support for a new upstream checkpoint, see the maintainer
tools in this repository. Most users should use supported model names or
checkpoints created by model.train(...).
CUDA is not available
What it means
CUDA is NVIDIA's GPU runtime. It is only available when your machine has a compatible NVIDIA GPU, driver, and PyTorch CUDA build.
If you are on a Mac or a CPU-only machine, torch.cuda.is_available() returns False. That is expected.
Fix
For CPU testing, let nitid choose the device automatically or use CPU:
from nitid import NITID
model = NITID("model1s", task="detect", device="cpu")
For CLI usage:
uv run nitid predict model=model1s task=detect source=image.jpg
For GPU usage, run on a Linux or Windows machine with an NVIDIA GPU and working drivers.
TensorRT export fails
What it means
TensorRT export requires NVIDIA-specific packages and a CUDA-capable GPU. It is not expected to work on macOS or CPU-only machines.
Fix
Install TensorRT manually on an NVIDIA machine:
pip install --extra-index-url https://pypi.nvidia.com tensorrt>=8.6
Then export:
uv run nitid export model=model1s task=detect format=tensorrt
If you do not need TensorRT, export to ONNX instead:
uv run nitid export model=model1s task=detect format=onnx
See the export guide for export options and constraints.
Docker container works but dfine command does not
What it means
The Docker container starts a Linux shell, but it does not automatically activate .venv.
So dfine may not be found even though nitid is installed inside the project environment.
Fix
Inside the container:
cd /app
.venv/bin/dfine --help
Or use uv run:
uv run nitid --help
From your host terminal:
docker exec nitid_container /app/.venv/bin/dfine --help
See the macOS Docker setup for the full container workflow.
Results.show() raises RuntimeError: Results.show() needs a display
What it means
show() opens a window, and there is nowhere to open one: a server, a container or an SSH session
without X11 or Wayland. nitid installs the headless OpenCV build so that import nitid works on
those machines, and show() then falls back to matplotlib. It raises this error only when matplotlib
cannot display anything either.
Fix
Write the image to disk, or take it as an array:
result.save("out.jpg")
image = result.plot() # HWC BGR numpy array
In Jupyter, show() renders inline through matplotlib.
ImportError: libGL.so.1 when importing nitid
What it means
The GUI build of OpenCV (opencv-python) is installed, and it needs system graphics libraries that
slim or server images do not have. nitid itself depends on opencv-python-headless, which does not
need them. opencv-python usually arrives with another package; the track extra's trackers
dependency requires it, for example. When both builds are installed, they share the cv2 module,
and whichever was installed last wins.
Fix
Make the headless build the one that provides cv2:
pip uninstall -y opencv-python
pip install --force-reinstall --no-deps opencv-python-headless
Or install the system library instead: apt-get install -y libgl1 libglib2.0-0.
Still stuck?
Run these checks from the repository root and include the output when asking for help:
git status
python --version
uv run nitid --help
uv run pytest tests/unit
If you are using Docker, also include:
docker compose ps
docker exec nitid_container /app/.venv/bin/dfine --help