Skip to content

[codex] Clarify self-update guidance for sudo installs #7004

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
llewellyn-sl wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

[codex] Clarify self-update guidance for sudo installs #7004

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,8 @@ To install Nextflow with the self-installing package:

:::{warning}
Nextflow updates its executable during the self-install process, therefore the update can fail if the executable is placed in a directory with restricted permissions.

Avoid installing the `nextflow` executable into a root-owned location such as `/usr/local/bin` with `sudo` if you plan to use `nextflow self-update`. If the executable is not writable by your normal user account, self-updates can fail and may leave the installation in a broken state. Prefer a user-writable location such as `$HOME/.local/bin`.
:::

4. Confirm Nextflow is installed correctly:
Expand Down
9 changes: 9 additions & 0 deletions docs/updating-nextflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,17 @@ When updating from an edge release to a stable release, you must explicitly set

:::{warning}
Nextflow will update its executable during the self-update process. The update can fail if the Nextflow executable is in a directory with restricted permissions.

Do not run `nextflow self-update` with `sudo`. If the executable or framework directory becomes owned by `root`, subsequent Nextflow commands can fail with `Permission denied` errors for your normal user account.
:::

If `self-update` fails after a `sudo` install or update, recover the installation with the following steps:

1. Remove the root-owned framework directory for the affected version, for example `sudo rm -rf ~/.nextflow/framework/<version>`.
2. If needed, remove or replace a root-owned `nextflow` executable that was installed into a protected location such as `/usr/local/bin`.
3. Reinstall Nextflow in a user-writable location such as `$HOME/.local/bin`.
4. Run `nextflow info` or `nextflow -v` to confirm the installation works again.

## Version selection

The `NXF_VER` environment variable can be used to define which version of Nextflow to use. To switch to a specific version of Nextflow for a single run, set the `NXF_VER` environment variable in your execution command. For example:
Expand Down
Loading