Skip to content

docs: update isolated installation instructions - #434

Merged
ekalinin merged 2 commits into
ekalinin:masterfrom
jihtsan:codex/423-install-docs
Oct 15, 2026
Merged

ekalinin merged 2 commits into
ekalinin:masterfrom
jihtsan:codex/423-install-docs

Conversation

@jihtsan

@jihtsan jihtsan commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

The installation guide recommends removed easy_install tooling and changing system Python with sudo pip. Update it to use isolated installations, addressing #423 and the installation review feedback.

  • Document pipx installation, pipx ensurepath, restarting the terminal, and how to target a project virtual environment with nodeenv -p.
  • Use .venv for the Python environment so it does not collide with the later nodeenv env example. Explain the Debian/Ubuntu python3-venv prerequisite.
  • Put source/editable installs inside the activated virtual environment; use double quotes around the Git URL so the example also works in Windows cmd.
  • Add Python-launcher cmd examples and direct PowerShell executable invocations that do not require changing execution policy.
  • State Python 3 and the CPython 3.10–3.14 CI coverage instead of repeating stale Python 2 support metadata. Keep dpkg instructions connected to a source checkout.

Validation on macOS with CPython 3.13.12, using temporary build/install directories:

  • Parsed the complete README with docutils at warning-as-error level; git diff --check passed.
  • Built this checkout with uv build --wheel --no-build-isolation --python <validation-python> --out-dir <temporary-dist> <exported-checkout>.
  • In a fresh .venv, python -m pip install --no-deps <wheel>, nodeenv --version, source nodeenv.py --help, and nodeenv --node=system env passed. Confirmed .venv and env coexist; the old Python environment name env reproduces the directory collision (exit 2).
  • Local editable install passed. The documented Git editable URL also installed successfully with python -m pip install --no-deps --no-build-isolation -e "git+https://github.com/ekalinin/nodeenv.git#egg=nodeenv", followed by nodeenv --version.
  • With isolated PIPX_HOME/PIPX_BIN_DIR, pipx installed the built wheel, the command ran, and nodeenv --node=system -p .venv targeted a fresh project environment. Checked pipx ensurepath --help; did not change the host shell PATH configuration.

Windows cmd/PowerShell and Debian/Ubuntu apt/dpkg commands were reviewed but not executed. Node download/compilation and the full runtime test suite were not run for this README-only change. Russian README and generated/site documentation remain follow-up work as requested in review.

Prepared and validated with Codex assistance.

Closes #423.

@ekalinin ekalinin left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the PR! A few things before merging:

  1. Python versions. 2.7 no longer works: find_system_node() uses shutil.which (nodeenv.py:207), so --node=system and --prefer-system fail with AttributeError. CI only covers 3.10-3.14. python_requires in setup.py is stale, so please drop 2.7 here rather than copying it.

  2. Editable install. It's shown outside the venv with python. That means PEP 668 errors on Debian 12+/Ubuntu 23.04+/Homebrew (the #423 case), and python may not exist at all. The single quotes also break in cmd. Suggested line:

    (env) $ python -m pip install -e "git+https://github.com/ekalinin/nodeenv.git#egg=nodeenv"
    
  3. Venv name env. It collides with nodeenv env in Usage: following the README in order ends with Environment already exists: env. Another name, e.g. .venv, avoids that.

  4. dpkg line. or on Debian using dpkg_:: now dangles after "Alternatively, use the local installation below."

Minor:

  • pipx: mention pipx ensurepath, since nodeenv is only on PATH if ~/.local/bin is.
  • pipx + -p: with no venv activated, Node.js goes into nodeenv's own pipx venv and is lost on pipx reinstall.
  • Debian/Ubuntu: python3 -m venv needs the python3-venv package.
  • Windows: python3 isn't reliable with a python.org install (py -m venv env), and the default execution policy blocks Activate.ps1.
  • FYI: site/index.html and README.ru.rst still have the old instructions. Fine as a follow-up.

@ekalinin
ekalinin merged commit 0c67226 into ekalinin:master Oct 15, 2026
26 checks passed
@ekalinin

Copy link
Copy Markdown
Owner

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

README install section is outdated

2 participants