Merge pull request #2067 from native-api/readme

Update setup instructions in the Readme
This commit is contained in:
Anton Petrov 2021-09-20 07:33:50 +03:00 committed by GitHub
commit 02c44942c6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 174 additions and 179 deletions

284
README.md
View file

@ -46,6 +46,10 @@ This project was forked from [rbenv](https://github.com/rbenv/rbenv) and
* [Choosing the Python Version](#choosing-the-python-version) * [Choosing the Python Version](#choosing-the-python-version)
* [Locating the Python Installation](#locating-the-python-installation) * [Locating the Python Installation](#locating-the-python-installation)
* **[Installation](#installation)** * **[Installation](#installation)**
* [Prerequisites](#prerequisites)
* [Homebrew in macOS](#homebrew-in-macos)
* [Windows](#windows)
* [Automatic installer](#automatic-installer)
* [Basic GitHub Checkout](#basic-github-checkout) * [Basic GitHub Checkout](#basic-github-checkout)
* [Upgrading](#upgrading) * [Upgrading](#upgrading)
* [Homebrew on macOS](#homebrew-on-macos) * [Homebrew on macOS](#homebrew-on-macos)
@ -168,11 +172,11 @@ We'd recommend to install pyenv-virtualenv as well if you have some plan to play
## Installation ## Installation
### Prerequisites: ### Prerequisites
For pyenv to install python correctly you should [**install the Python build dependencies**](https://github.com/pyenv/pyenv/wiki#suggested-build-environment). For pyenv to install python correctly you should [**install the Python build dependencies**](https://github.com/pyenv/pyenv/wiki#suggested-build-environment).
### Homebrew on macOS ### Homebrew in macOS
1. Consider installing with [Homebrew](https://brew.sh): 1. Consider installing with [Homebrew](https://brew.sh):
```sh ```sh
@ -181,9 +185,20 @@ For pyenv to install python correctly you should [**install the Python build dep
``` ```
2. Then follow the rest of the post-installation steps under [Basic GitHub Checkout](https://github.com/pyenv/pyenv#basic-github-checkout), starting with #2 ("Configure your shell's environment for Pyenv"). 2. Then follow the rest of the post-installation steps under [Basic GitHub Checkout](https://github.com/pyenv/pyenv#basic-github-checkout), starting with #2 ("Configure your shell's environment for Pyenv").
If you're on Windows, consider using @kirankotari's [`pyenv-win`](https://github.com/pyenv-win/pyenv-win) fork. (Pyenv does not work in Windows outside the Windows Subsystem for Linux.)
### The automatic installer ### Windows
Pyenv does not officially support Windows and does not work in Windows outside
the Windows Subsystem for Linux.
Moreover, even there, the Pythons it installs are not native Windows versions
but rather Linux versions run through a compatibility layer --
so you won't get Windows-specific functionality.
If you're in Windows, we recommend using @kirankotari's [`pyenv-win`](https://github.com/pyenv-win/pyenv-win) fork --
which does install native Windows Python versions.
### Automatic installer
Visit our other project: Visit our other project:
https://github.com/pyenv/pyenv-installer https://github.com/pyenv/pyenv-installer
@ -206,139 +221,156 @@ easy to fork and contribute any changes back upstream.
2. **Configure your shell's environment for Pyenv** 2. **Configure your shell's environment for Pyenv**
**Note:** The below instructions for specific shells are designed for common shell setups. **Note:** The below instructions for specific shells are designed for common shell setups;
If you have an uncommon setup and they don't work for you, they also install shell functions into interactive shells only.
use the guidance text and the [Advanced Configuration](#advanced-configuration) If you have an uncommon setup and/or needs and they don't work for you,
use the [Advanced Configuration](#advanced-configuration)
section below to figure out what you need to do in your specific case. section below to figure out what you need to do in your specific case.
1. **Adjust the session-wide environment for your account.** Define **General MacOS note:**
the `PYENV_ROOT` environment variable to point to the path where Make sure that your terminal app is configured to run the shell as a login shell
you cloned the Pyenv repo, add the `pyenv` command-line utility to your `PATH`, (especially if you're using an alternative terminal app and/or shell).
run the output of `pyenv init --path` to enable shims. The configuration samples for MacOS are written under this assumption and won't work otherwise.
These commands need to be added into your shell startup files in such a way - For **Bash**:
that _they are executed only once per session, by its login shell._
This typically means they need to be added into a per-user shell-specific
`~/.*profile` file, _and_ into `~/.profile`, too, so that they are also
run by GUI managers (which typically act as a `sh` login shell).
**MacOS note:** If you installed Pyenv with Homebrew, you don't need - **If your `~/.profile` sources `~/.bashrc` (Debian, Ubuntu, Mint):**
to add the `PYENV_ROOT=` and `PATH=` lines.
You also don't need to add commands into `~/.profile` if your shell doesn't use it.
- For **Bash**: ~~~bash
# the sed invocation inserts the lines at the start of the file
# after any initial comment lines
sed -iEe '/^([^#]|$)/ {a \
export PYENV_ROOT="$HOME/.pyenv"
a \
export PATH="$PYENV_ROOT/bin:$PATH"
a \
' -e ':a' -e '$!{n;ba};}' ~/.profile
echo 'eval "$(pyenv init --path)"' >>~/.profile
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
~~~
- **If your `~/.bash_profile` sources `~/.bashrc` (Red Hat, Fedora, CentOS):**
~~~ bash ~~~ bash
sed -iEe '/^([^#]|$)/ {a \
export PYENV_ROOT="$HOME/.pyenv"
a \
export PATH="$PYENV_ROOT/bin:$PATH"
a \
' -e ':a' -e '$!{n;ba};}' ~/.bash_profile
echo 'eval "$(pyenv init --path)"' >> ~/.bash_profile
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
echo 'eval "$(pyenv init --path)"' >> ~/.profile echo 'eval "$(pyenv init --path)"' >> ~/.profile
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
~~~ ~~~
- **If your `~/.profile` sources `~/.bashrc` (Debian, Ubuntu, Mint):** - **If you have no `~/.bash_profile` and your `/etc/profile` sources `~/.bashrc` (SUSE):**
Put these lines into `~/.profile` _before_ the part that sources `~/.bashrc`: ~~~bash
~~~bash echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
export PYENV_ROOT="$HOME/.pyenv" echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
export PATH="$PYENV_ROOT/bin:$PATH" echo 'eval "$(pyenv init --path)"' >> ~/.profile
~~~
And put this line at the _bottom_ of `~/.profile`: echo 'if command -v pyenv >/dev/null; then eval "$(pyenv init -)"; fi' >> ~/.bashrc
~~~bash ~~~
eval "$(pyenv init --path)"
~~~
<!--This is an alternative option and needn't be replicated to `pyenv init`--> - **Otherwise if you have no stock `~/.profile` or `~/.bash_profile` (MacOS):**
Alternatively, for an automated installation, you can run the following:
~~~ bash
echo -e 'if shopt -q login_shell; then' \
'\n export PYENV_ROOT="$HOME/.pyenv"' \
'\n export PATH="$PYENV_ROOT/bin:$PATH"' \
'\n eval "$(pyenv init --path)"' \
'\nfi' >> ~/.bashrc
echo -e 'if [ -z "$BASH_VERSION" ]; then'\
'\n export PYENV_ROOT="$HOME/.pyenv"'\
'\n export PATH="$PYENV_ROOT/bin:$PATH"'\
'\n eval "$(pyenv init --path)"'\
'\nfi' >>~/.profile
~~~
**Note:** If you have `~/.bash_profile`, make sure that it too executes the above-added commands, ~~~bash
e.g. by copying them there or by `source`'ing `~/.profile`. echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
echo 'eval "$(pyenv init --path)"' >> ~/.profile
echo 'if [ -n "$PS1" -a -n "$BASH_VERSION" ]; then source ~/.bashrc; fi' >> ~/.profile
- For **Zsh**: echo 'eval "$(pyenv init -)"' >> ~/.bashrc
~~~
- **MacOS, if Pyenv is installed with Homebrew:** In MacOS, make sure that your terminal app runs the shell as a login shell.
~~~ zsh - **Temporary environments (CI, batch jobs):**
echo 'eval "$(pyenv init --path)"' >> ~/.zprofile
~~~
- **MacOS, if Pyenv is installed with a Git checkout:** In CI/build environments, paths and the environment are usually already set up for you
in one of the above ways.
You may only need to install Pyenv as a shell function into the (noninteractive) shell
that runs the batch script, and only if you need subcommands that require `pyenv`
to be a shell function (e.g. `shell` and Pyenv-Virtualenv's `activate`).
~~~ zsh ~~~bash
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zprofile echo 'eval "$(pyenv init -)"'
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zprofile ~~~
echo 'eval "$(pyenv init --path)"' >> ~/.zprofile
~~~
- **Other OSes:** **General Bash warning**: There are some systems where the `BASH_ENV` variable is configured
to point to `.bashrc`. On such systems, you should almost certainly put the
`eval "$(pyenv init -)"` line into `.bash_profile`, and **not** into `.bashrc`. Otherwise, you
may observe strange behaviour, such as `pyenv` getting into an infinite loop.
See [#264](https://github.com/pyenv/pyenv/issues/264) for details.
Same as for Bash above, but add the commands into both `~/.profile`
and `~/.zprofile`. - For **Zsh**:
- **MacOS, if Pyenv is installed with Homebrew:**
~~~ zsh
echo 'eval "$(pyenv init --path)"' >> ~/.zprofile
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
~~~
Make sure that your terminal app runs the shell as a login shell.
- **MacOS, if Pyenv is installed with a Git checkout:**
~~~ zsh
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zprofile
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zprofile
echo 'eval "$(pyenv init --path)"' >> ~/.zprofile
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
~~~
Make sure that your terminal app runs the shell as a login shell.
- **Other OSes:**
~~~ zsh
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zprofile
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zprofile
echo 'eval "$(pyenv init --path)"' >> ~/.zprofile
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
echo 'eval "$(pyenv init --path)"' >> ~/.profile
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
~~~
- For **Fish shell**: - For **Fish shell**:
Execute this interactively: Execute this interactively:
~~~ fish ~~~ fish
set -Ux PYENV_ROOT $HOME/.pyenv set -Ux PYENV_ROOT $HOME/.pyenv
set -U fish_user_paths $PYENV_ROOT/bin $fish_user_paths set -U fish_user_paths $PYENV_ROOT/bin $fish_user_paths
~~~ ~~~
And add this to `~/.config/fish/config.fish`: And add this to `~/.config/fish/config.fish`:
~~~ fish ~~~ fish
status is-interactive; and pyenv init --path | source status is-login; and pyenv init --path | source
status is-interactive; and pyenv init - | source
~~~ ~~~
If Fish is not your login shell, also follow the Bash/Zsh instructions to add to `~/.profile`. If Fish is not your login shell, also follow the Bash/Zsh instructions to add to `~/.profile`.
**Proxy note**: If you use a proxy, export `http_proxy` and `https_proxy`, too. **Proxy note**: If you use a proxy, export `http_proxy` and `https_proxy`, too.
2. **Add `pyenv` into your shell** by running the output of `pyenv init -`
to enable autocompletion and all subcommands.
This command needs to run at startup of any interactive shell instance. 4. **Restart your login session for the changes to profile files to take effect.**
In an interactive login shell, it needs to run _after_ the commands
from the previous step.
- For **bash**:
~~~ bash
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
~~~
- **If your `/etc/profile` sources `~/.bashrc` (SUSE):**
~~~bash
echo 'if command -v pyenv >/dev/null; then eval "$(pyenv init -)"; fi' >> ~/.bashrc
~~~
- For **Zsh**:
~~~ zsh
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
~~~
- For **Fish shell**:
Add this to `~/.config/fish/config.fish`:
~~~ fish
pyenv init - | source
~~~
**General warning**: There are some systems where the `BASH_ENV` variable is configured
to point to `.bashrc`. On such systems you should almost certainly put the above-mentioned line
`eval "$(pyenv init -)"` into `.bash_profile`, and **not** into `.bashrc`. Otherwise you
may observe strange behaviour, such as `pyenv` getting into an infinite loop.
See [#264](https://github.com/pyenv/pyenv/issues/264) for details.
4. **Restart your login session for the changes to take effect.**
E.g. if you're in a GUI session, you need to fully log out and log back in. E.g. if you're in a GUI session, you need to fully log out and log back in.
In MacOS, restarting terminal windows is enough (because MacOS runs shells In MacOS, restarting terminal windows is enough (because MacOS runs shells
@ -424,30 +456,52 @@ profile is doing.
`pyenv init` is the only command that crosses the line of loading `pyenv init` is the only command that crosses the line of loading
extra commands into your shell. Coming from RVM, some of you might be extra commands into your shell. Coming from RVM, some of you might be
opposed to this idea. Here's what `pyenv init` actually does. opposed to this idea.
Step 1 is done by `eval "$(pyenv init --path)"`, the others are done by
`eval "$(pyenv init -)"`. Also see the [Environment variables](#environment-variables) section
for the environment variables that control Pyenv's behavior.
1. **Sets up your shims path.** This is the only requirement for pyenv to * `eval "$(pyenv init --path)"`:
function properly. You can do this by hand by prepending
`$(pyenv root)/shims` to your `$PATH`.
2. **Installs autocompletion.** This is entirely optional but pretty 1. **Sets up your shims path.** This is the only requirement for pyenv to
useful. Sourcing `$(pyenv root)/completions/pyenv.bash` will set that function properly. You can do this by hand by prepending
up. There is also a `$(pyenv root)/completions/pyenv.zsh` for Zsh `$(pyenv root)/shims` to your `$PATH`.
users.
3. **Rehashes shims.** From time to time you'll need to rebuild your `eval "$(pyenv init --path)"` is supposed to be run in your session's login
shim files. Doing this on init makes sure everything is up to shell startup script -- so that all processes in the session get access to
date. You can always run `pyenv rehash` manually. Pyenv's functionality and it only runs once,
avoiding breaking `PATH` in nested shells
(e.g. shells started from editors/IDEs).
4. **Installs the sh dispatcher.** This bit is also optional, but allows In Linux, GUI managers typically act as a `sh` login shell, running
pyenv and plugins to change variables in your current shell, making `/etc/profile` and `~/.profile` at their startup. MacOS' GUI doesn't do that,
commands like `pyenv shell` possible. The sh dispatcher doesn't do so its terminal emulator apps run their shells as login shells by default
anything crazy like override `cd` or hack your shell prompt, but if to compensate.
for some reason you need `pyenv` to be a real script rather than a
shell function, you can safely skip it.
* `eval "$(pyenv init -)"`:
1. **Installs autocompletion.** This is entirely optional but pretty
useful. Sourcing `$(pyenv root)/completions/pyenv.bash` will set that
up. There is also a `$(pyenv root)/completions/pyenv.zsh` for Zsh
users.
2. **Rehashes shims.** From time to time you'll need to rebuild your
shim files. Doing this on init makes sure everything is up to
date. You can always run `pyenv rehash` manually.
3. **Installs `pyenv` into the current shell as a shell function.**
This bit is also optional, but allows
pyenv and plugins to change variables in your current shell, making
commands like `pyenv shell` possible. The sh dispatcher doesn't do
anything crazy like override `cd` or hack your shell prompt, but if
for some reason you need `pyenv` to be a real script rather than a
shell function, you can safely skip it.
`eval "$(pyenv init -)"` is supposed to run at any interactive shell's
startup (including nested shells) so that you get completion and
convenience shell functions.
To see exactly what happens under the hood for yourself, run `pyenv init -` To see exactly what happens under the hood for yourself, run `pyenv init -`
or `pyenv init --path`. or `pyenv init --path`.

View file

@ -93,68 +93,9 @@ function help_() {
{ {
echo echo
echo '# (The below instructions are intended for common' echo '# See the README for instructions on how to set up'
echo '# shell setups. See the README for more guidance' echo '# your shell environment for Pyenv.'
echo '# if they don'\''t apply and/or don'\''t work for you.)'
echo echo
case "$shell" in
fish )
echo "# Add pyenv executable to PATH by running"
echo "# the following interactively:"
echo
echo 'set -Ux PYENV_ROOT $HOME/.pyenv'
echo 'set -U fish_user_paths $PYENV_ROOT/bin $fish_user_paths'
echo
echo "# Load pyenv automatically by appending"
echo "# the following to ~/.config/fish/config.fish:"
echo
echo 'status is-interactive; and pyenv init --path | source'
echo 'pyenv init - | source'
echo
echo "# If fish is not your login shell,"
echo "# add the following to ~/.profile:"
echo
echo 'export PYENV_ROOT="$HOME/.pyenv"'
echo 'export PATH="$PYENV_ROOT/bin:$PATH"'
echo 'eval "$(pyenv init --path)"'
echo
;;
* )
echo '# Add pyenv executable to PATH and'
echo '# enable shims by adding the following'
case "$shell" in
bash|ksh )
echo '# to ~/.profile:'
;;
* )
echo '# to ~/.profile and '"${profile}"':'
;;
esac
echo
echo 'export PYENV_ROOT="$HOME/.pyenv"'
echo 'export PATH="$PYENV_ROOT/bin:$PATH"'
echo 'eval "$(pyenv init --path)"'
echo
if [[ $shell == "bash" ]]; then
echo '# If your ~/.profile sources '"${rc}"','
echo '# the lines need to be inserted before the part'
echo '# that does that. See the README for another option.'
echo
echo '# If you have '"${profile}"', make sure that it'
echo '# also executes the above lines -- e.g. by'
echo '# copying them there or by sourcing ~/.profile'
echo
fi
echo "# Load pyenv into the shell by adding"
echo "# the following to ${rc}:"
echo
echo 'eval "$(pyenv init -)"'
echo
echo '# Make sure to restart your entire logon session'
echo '# for changes to profile files to take effect.'
echo
;;
esac
} >&2 } >&2
} }

View file

@ -53,7 +53,7 @@ OUT
@test "fish instructions" { @test "fish instructions" {
run pyenv-init fish run pyenv-init fish
assert [ "$status" -eq 1 ] assert [ "$status" -eq 1 ]
assert_line 'pyenv init - | source' assert_line '# See the README for instructions on how to set up'
} }
@test "option to skip rehash" { @test "option to skip rehash" {