fix(cli): make uv tool install the front door for nemo-platform #1248
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -12,7 +12,7 @@ Install NeMo Platform and start working with AI agents. | |
| - Python 3.12-3.13 | ||
| - An API key from one of: [NVIDIA Build](https://build.nvidia.com), [OpenAI](https://platform.openai.com/api-keys), [Anthropic](https://console.anthropic.com/settings/keys), [Google Gemini](https://aistudio.google.com/apikey), or a local [Ollama](https://ollama.com) instance (no key needed) | ||
| - 16 GB available disk space and 8 GB RAM | ||
| - For the PyPI install: [uv](https://docs.astral.sh/uv/) `>=0.9.14`, or `pip` in a Python environment | ||
| - For the source checkout install: [Git](https://git-scm.com/), GNU Make, [uv](https://docs.astral.sh/uv/) `>=0.9.14`, [Node.js (≥22.23.2, \<23)](https://nodejs.org/en/download) satisfying `web/package.json`, and [pnpm](https://pnpm.io/installation) | ||
|
|
||
| ## Install | ||
|
|
@@ -21,21 +21,35 @@ Choose the install path that matches what you want to do. | |
|
|
||
| ### Install from PyPI | ||
|
|
||
| Use the [PyPI package](https://pypi.org/project/nemo-platform/) for the quickest local install. The `all` extra includes the SDK, CLI, platform services, and default first-party plugins; drop it for the SDK and CLI alone. | ||
|
|
||
| <Tabs> | ||
|
|
||
| <Tab title="uv tool (recommended)"> | ||
|
|
||
| One command, `nemo` available everywhere, nothing to activate. | ||
|
|
||
| ```bash | ||
| uv tool install "nemo-platform[all]" | ||
| ``` | ||
|
Comment on lines
+33
to
+34
Contributor
There was a problem hiding this comment. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- docs/get-started/setup.mdx ---'
cat -n docs/get-started/setup.mdx | sed -n '1,80p'
printf '%s\n' '--- packages/nemo_platform/README.md ---'
cat -n packages/nemo_platform/README.md | sed -n '1,60p'
printf '%s\n' '--- uv tool references ---'
rg -n -i 'uv tool|PATH|shell reload|nemo-platform\[all\]' docs packages/nemo_platform README.md 2>/dev/null || trueRepository: NVIDIA-NeMo/nemo-platform Length of output: 50384 🏁 Script executed: #!/bin/bash
set -u
printf '%s\n' '--- cited documentation ranges ---'
sed -n '25,42p' docs/get-started/setup.mdx
printf '%s\n' '--- cited README range ---'
sed -n '20,36p' packages/nemo_platform/README.md
printf '%s\n' '--- uv availability and relevant help ---'
if command -v uv >/dev/null 2>&1; then
uv --version
uv tool --help | sed -n '1,160p'
printf '%s\n' '--- uv tool dir --bin ---'
uv tool dir --bin
else
printf '%s\n' 'uv is not installed in the sandbox'
fiRepository: NVIDIA-NeMo/nemo-platform Length of output: 1358 🌐 Web query:
💡 Result: When you install a tool using uv tool install, the tool's executables are placed in a specific executable directory (bin directory) [1][2][3]. For these tools to be accessible directly from your shell, this directory must be included in your system's PATH environment variable [1][4]. If the directory is not already in your PATH, uv will display a warning upon installation [1][2]. To resolve this, you can run the following command to automatically add the executable directory to your shell's configuration files: uv tool update-shell [1][5] After running this command, you will typically need to restart your shell session (or source your configuration file, e.g., source ~/.bashrc or source ~/.zshrc) for the changes to take effect and for the new PATH to be recognized [1][4]. You can locate the tool executable directory on your system by running: uv tool dir --bin [3] This ensures that the symlinks or copies of the tool's executables are correctly referenced by your shell [1][4]. Citations:
Document If the 📍 Affects 2 files
🤖 Prompt for AI AgentsSource: MCP tools 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- referenced documentation ---'
for f in docs/get-started/setup.mdx packages/nemo_platform/README.md; do
if [ -f "$f" ]; then
printf '\n### %s\n' "$f"
nl -ba "$f" | sed -n '20,55p'
else
printf 'MISSING %s\n' "$f"
fi
done
printf '%s\n' '--- package metadata and all extra ---'
rg -n -S --glob '!*node_modules*' \
'nemo-platform|optional-dependencies|extras_require|\[all\]|all\s*=|dependency|conflict|next release' \
pyproject.toml setup.py setup.cfg packages docs .github 2>/dev/null | sed -n '1,240p'
printf '%s\n' '--- repository files near package metadata ---'
git ls-files | rg '(^|/)(pyproject\.toml|setup\.py|setup\.cfg|requirements[^/]*|CHANGELOG|.*release.*|.*manifest.*)$' | sed -n '1,160p'Repository: NVIDIA-NeMo/nemo-platform Length of output: 33075 🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- setup instructions ---'
for f in docs/get-started/setup.mdx packages/nemo_platform/README.md; do
printf '\n### %s\n' "$f"
sed -n '20,55p' "$f"
done
printf '%s\n' '--- package metadata ---'
sed -n '1,220p' packages/nemo_platform/pyproject.toml
printf '%s\n' '--- relevant repository changes ---'
git diff --stat
git diff -- docs/get-started/setup.mdx packages/nemo_platform/README.md packages/nemo_platform/pyproject.toml | sed -n '1,260p'
printf '%s\n' '--- all references to the published install commands ---'
rg -n -F \
-e 'uv tool install "nemo-platform[all]"' \
-e 'pip install "nemo-platform[all]"' \
-e 'nemo-platform[all]' \
docs packages README.md 2>/dev/null | sed -n '1,220p'Repository: NVIDIA-NeMo/nemo-platform Length of output: 37354 🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- wrapper extra definitions ---'
rg -n -A12 -B4 \
'^\[project\.optional-dependencies\]|^all\s*=|^services\s*=|^core-service\s*=|^service' \
packages/nemo_platform/pyproject.toml | sed -n '1,260p'
printf '%s\n' '--- bundling documentation ---'
sed -n '1,155p' packages/nemo_platform/BUNDLING.md
printf '%s\n' '--- package version and release references ---'
rg -n -S \
'^\[tool\.hatch|version|release|0\.[0-9]+\.[0-9]+|next release|unresolved|conflict' \
packages/nemo_platform/pyproject.toml packages/nemo_platform/BUNDLING.md \
docs/about/release-notes/current-release.mdx .github/release* .github/workflows/release.yaml \
2>/dev/null | sed -n '1,240p'
printf '%s\n' '--- repository state ---'
git status --short
git log -5 --oneline -- packages/nemo_platform/pyproject.toml docs/get-started/setup.mdx packages/nemo_platform/README.mdRepository: NVIDIA-NeMo/nemo-platform Length of output: 32952 🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- recent dependency-related commits ---'
for c in 1c5a6b0e0 89868b26e 548ac20d8 76d1643aa; do
printf '\n### %s\n' "$c"
git show --stat --oneline "$c"
git show --format=fuller --no-ext-diff "$c" -- \
packages/nemo_platform/pyproject.toml \
docs/get-started/setup.mdx \
packages/nemo_platform/README.md \
plugins/nemo-agents/pyproject.toml \
uv.lock | sed -n '1,280p'
done
printf '%s\n' '--- resolver tooling availability ---'
command -v uv || true
command -v pip || true
command -v python3 || trueRepository: NVIDIA-NeMo/nemo-platform Length of output: 50383 🏁 Script executed: #!/bin/bash
set -eu
python3 - <<'PY'
import subprocess
import tomllib
from pathlib import Path
metadata = tomllib.loads(
Path("packages/nemo_platform/pyproject.toml").read_text(encoding="utf-8")
)
extras = metadata["project"]["optional-dependencies"]
assert extras["all"] == ["nemo-platform[services]"]
assert any(dep == "nemo-platform[plugins]" for dep in extras["services"])
assert any("nvidia-nat-core>=1.8.0,<1.9" == dep for dep in extras["nemo-agents-plugin"])
for path in (
Path("docs/get-started/setup.mdx"),
Path("packages/nemo_platform/README.md"),
):
text = path.read_text(encoding="utf-8")
assert text.count('uv tool install "nemo-platform[all]"') == 1
assert text.count('pip install "nemo-platform[all]"') == 1
print(f"{path}: both published commands are unpinned")
message = subprocess.check_output(
["git", "show", "-s", "--format=%B", "1c5a6b0e0"],
text=True,
)
required = (
"Published 0.3.0 still installs",
"this affects the next release",
"nemo-platform[all] resolves without the repo's override-dependencies",
)
for phrase in required:
assert phrase in message
print("1c5a6b0e0: records that 0.3.0 installs but the next release remains unresolved")
print("all -> services:", extras["all"])
print("NAT constraint:", next(
dep for dep in extras["nemo-agents-plugin"]
if dep.startswith("nvidia-nat-core")
))
PYRepository: NVIDIA-NeMo/nemo-platform Length of output: 283 🏁 Script executed: #!/bin/bash
set -eu
python3 - <<'PY'
import subprocess
from pathlib import Path
pyproject = Path("packages/nemo_platform/pyproject.toml").read_text(encoding="utf-8")
for expected in (
'all = ["nemo-platform[services]"]',
'"nemo-platform[plugins]"',
'"nvidia-nat-core>=1.8.0,<1.9"',
):
assert expected in pyproject, expected
for path in (
Path("docs/get-started/setup.mdx"),
Path("packages/nemo_platform/README.md"),
):
text = path.read_text(encoding="utf-8")
assert text.count('uv tool install "nemo-platform[all]"') == 1
assert text.count('pip install "nemo-platform[all]"') == 1
print(f"{path}: both published commands are unpinned")
message = subprocess.check_output(
["git", "show", "-s", "--format=%B", "1c5a6b0e0"],
text=True,
)
for phrase in (
"Published 0.3.0 still installs",
"this affects the next release",
"nemo-platform[all] resolves without the repo's override-dependencies",
):
assert phrase in message, phrase
print("1c5a6b0e0: records that 0.3.0 installs but the next release remains unresolved")
print("all -> services and NAT remains constrained to the 1.8 line")
PYRepository: NVIDIA-NeMo/nemo-platform Length of output: 458 Pin or gate the 📍 Affects 2 files
🤖 Prompt for AI Agents🎯 Functional Correctness | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- relevant files ---'
git ls-files 'docs/get-started/setup.mdx' 'packages/nemo_platform/README.md' \
| while IFS= read -r f; do
printf '\n--- %s ---\n' "$f"
wc -l "$f"
rg -n -C 5 'uv|python|requires-python|requires_python|Python|version' "$f" || true
done
printf '\n--- package and project metadata candidates ---\n'
git ls-files | rg '(^|/)(pyproject\.toml|setup\.py|setup\.cfg|.*requirements.*|.*uv.*|README\.md)$' \
| head -200
printf '\n--- Python requirement declarations ---\n'
rg -n -C 3 'requires-python|requires_python|python_requires|Programming Language :: Python|Python :: 3\.(12|13)|uv' \
--glob 'pyproject.toml' --glob 'setup.py' --glob 'setup.cfg' --glob '*.md' --glob '*.mdx' . \
| head -300Repository: NVIDIA-NeMo/nemo-platform Length of output: 35084 🏁 Script executed: #!/bin/bash
set -eu
for f in packages/nemo_platform/pyproject.toml pyproject.toml .cursor/rules/uv.mdc README.md; do
if git ls-files --error-unmatch "$f" >/dev/null 2>&1; then
printf '\n--- %s ---\n' "$f"
wc -l "$f"
rg -n -C 6 'requires-python|requires_python|python|tool\.uv|uv|index|resolution|conflict|nemo-platform' "$f" | head -240
fi
done
printf '\n--- all nemo-platform Python requirements ---\n'
rg -n -C 4 'requires-python|requires_python|python_requires' \
packages/nemo_platform/pyproject.toml sdk/python/nemo-platform/pyproject.toml \
pyproject.toml 2>/dev/null || true
printf '\n--- install command occurrences ---\n'
rg -n -C 2 'uv tool install "nemo-platform\[all\]"|uv tool install' \
docs/get-started/setup.mdx packages/nemo_platform/README.md README.mdRepository: NVIDIA-NeMo/nemo-platform Length of output: 27416 🌐 Web query:
💡 Result: When using uv tool install, the default Python interpreter selection and the handling of requires-python constraints behave according to the following logic: Python Interpreter Selection By default, uv attempts to select an appropriate Python interpreter for the tool environment [1]. It uses standard Python discovery logic [1], which searches for interpreters in the PATH, virtual environments, and managed installations (via uv python install) [2][3][4]. If no specific interpreter is requested via the --python flag, uv follows a preference hierarchy [5][4]: 1. The python-preference setting (defaulting to managed) determines whether uv prioritizes its own managed installations or system-installed interpreters [5][4]. 2. If multiple candidates exist, uv prioritizes newer versions among managed installations, while for system interpreters, it typically selects the first compatible version found [5][4]. 3. If no suitable Python version is found, uv may automatically download and install a required managed Python version [3][4]. Requires-Python Handling Historically, uv tool install did not automatically infer Python requirements from a package's metadata, which often led to resolution failures if the default discovered interpreter was incompatible [6][7]. However, recent updates have introduced mechanisms to improve this [8]: - Inference: uv can now inspect the requires-python metadata (e.g., from pyproject.toml or wheel distribution metadata) to refine the Python version request [8]. - Resolution and Refinement: If initial resolution fails due to an incompatible interpreter, uv can automatically attempt to refine the choice—including downloading a compliant managed Python version—to satisfy the tool's requirements [9]. For precise control, you can always explicitly specify the required Python version or range using the --python flag [1], for example: uv tool install --python ">=3.10" This approach overrides default discovery and ensures the tool is installed in an environment using a compatible interpreter [1][7]. Citations:
🌐 Web query:
💡 Result: In Citations:
🌐 Web query:
💡 Result: When using Citations:
🏁 Script executed: #!/bin/bash
set -eu
if command -v uv >/dev/null 2>&1; then
printf '%s\n' '--- installed uv version ---'
uv --version
printf '%s\n' '--- uv tool install options ---'
uv tool install --help | rg -n -C 2 -- '--python|requires-python|version|managed'
else
printf '%s\n' 'uv is not installed in the sandbox\n'
fiRepository: NVIDIA-NeMo/nemo-platform Length of output: 200 🌐 Web query:
💡 Result: When using the uv tool install command, uv ignores the requires-python constraint specified in a pyproject.toml file [1][2]. While uv uses standard Python version discovery logic to create an isolated virtual environment for the tool, it explicitly excludes non-global Python version requests, including.python-version files and requires-python metadata [1][2]. If you need to install a tool with a specific Python version requirement, you must explicitly provide the --python option during the installation command [1][2]. For example: uv tool install --python If the Python version selected for the tool is later uninstalled, the tool environment will be broken and the tool may become unusable [1][2]. Citations: 🌐 Web query:
💡 Result: To specify a Python version when installing a tool with the uv package manager, you can use the --python option [1][2]. For example, to install a package with a specific Python version using uv, you would use the following syntax [1][2]: uv tool install --python Each tool installed via uv is linked to a specific Python version [1][2]. When using the --python option, uv uses its standard Python version discovery logic to locate the requested version, while ignoring local configuration files like.python-version or pyproject.toml requirements [1][2]. If the specified Python version is later uninstalled from your system, the tool environment will become broken and the tool may no longer function [1][2]. Citations: 🌐 Web query:
💡 Result: To install Python tools for personal use, the current recommended approach is to use tools like uv or pipx, which create isolated environments for each application to prevent dependency conflicts. Using uv, you can install a tool into a persistent environment where its executables are added to your PATH, allowing you to run them directly [1][2]. To install a tool using uv, use the following command: uv tool install For example, to install ruff: uv tool install ruff When installed this way, uv places the tool's executables in a bin directory [1][2]. If the directory is not already in your PATH, you can update your shell configuration using: uv tool update-shell If you want to specify a particular Python version for the tool, you can provide it during installation [1][2]: uv tool install --python 3.10 ruff Unlike installing packages with standard pip into your global environment, using these dedicated tool managers ensures that each application's dependencies remain isolated [1][2]. Citations: 🌐 Web query:
💡 Result: The Requires-Python metadata field is a specification used in Python packaging to declare the range of Python versions that a package or project supports [1][2][3]. This field is typically defined in a projects configuration file, such as pyproject.toml. When working with packaging tools and environments, the Requires-Python value serves as a constraint for installation. For instance, if a user attempts to install a package into an environment running a Python version outside the range specified in Requires-Python, the packaging tool should identify this incompatibility and prevent the installation. However, usage can vary by tool context. For example, some modern tooling like uv, when managing isolated tool environments, may ignore the Requires-Python value from a projects pyproject.toml in favor of specific version discovery logic or explicit user-provided version requirements [1][3]. In these specific tool environments, the tool links the environment to a designated Python version rather than strictly adhering to the metadata constraint defined within the project itself [1][2]. Citations:
Pin the tool environment to Python 3.13. 📍 Affects 2 files
🤖 Prompt for AI AgentsSource: MCP tools |
||
|
|
||
| </Tab> | ||
|
|
||
| <Tab title="Virtual environment"> | ||
|
|
||
| Use when you also import the SDK from your own code. `nemo` works only while the environment is active. | ||
|
|
||
| ```bash | ||
| python -m venv .venv | ||
| source .venv/bin/activate | ||
| pip install "nemo-platform[all]" | ||
| ``` | ||
|
|
||
| </Tab> | ||
|
|
||
| </Tabs> | ||
|
|
||
| Continue with `nemo setup`. | ||
|
|
||
| ### Install from source | ||
|
|
||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. | ||
| # SPDX-License-Identifier: Apache-2.0 | ||
|
|
||
| """How this NeMo Platform install was created.""" | ||
|
|
||
| from __future__ import annotations | ||
|
|
||
| import sys | ||
| from pathlib import Path | ||
|
|
||
|
|
||
| def services_extra_install_command() -> str: | ||
| """Return the command that adds the packaged service dependencies here. | ||
|
|
||
| ``uv tool install`` environments are managed by uv and are not meant to be | ||
| edited with pip; re-running the tool install with the extra upgrades them | ||
| in place. uv marks such an environment with a ``uv-receipt.toml`` at its | ||
| root, which is what distinguishes it from an ordinary virtual environment. | ||
| """ | ||
| if (Path(sys.prefix) / "uv-receipt.toml").is_file(): | ||
| return "uv tool install 'nemo-platform[all]'" | ||
| return "pip install 'nemo-platform[all]'" |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. | ||
| # SPDX-License-Identifier: Apache-2.0 | ||
|
|
||
| from __future__ import annotations | ||
|
|
||
| import sys | ||
| from pathlib import Path | ||
|
|
||
| import pytest | ||
| from nemo_platform_ext.local.install import services_extra_install_command | ||
|
|
||
|
|
||
| @pytest.mark.parametrize( | ||
| ("uv_tool_env", "expected"), | ||
| [ | ||
| (False, "pip install 'nemo-platform[all]'"), | ||
| (True, "uv tool install 'nemo-platform[all]'"), | ||
| ], | ||
| ) | ||
| def test_services_extra_install_command_matches_install_method( | ||
| tmp_path: Path, monkeypatch: pytest.MonkeyPatch, uv_tool_env: bool, expected: str | ||
| ) -> None: | ||
| if uv_tool_env: | ||
| (tmp_path / "uv-receipt.toml").write_text("[tool]\n") | ||
| monkeypatch.setattr(sys, "prefix", str(tmp_path)) | ||
|
|
||
| assert services_extra_install_command() == expected |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
should we just prefer the
uvway, tool or not?