github/pyenv
1
0
Fork 0
mirror of https://github.com/pyenv/pyenv.git synced 2024-11-21 20:47:00 -05:00
Code Issues Projects Releases Packages Wiki Activity

README.md: Minor edits and formatting

Browse source
This commit is contained in:
Tony 2014-03-19 15:00:54 -04:00
parent cf89abaacf
commit d1f78c2716
1 changed files with 65 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

98
README.md
View file

@ -9,7 +9,8 @@ tools that do one thing well.
This project was forked from [rbenv](https://github.com/sstephenson/rbenv) and This project was forked from [rbenv](https://github.com/sstephenson/rbenv) and
[ruby-build](https://github.com/sstephenson/ruby-build), and modified for Python. [ruby-build](https://github.com/sstephenson/ruby-build), and modified for Python.
<img src="http://gyazo.com/9c829fafdf5e58880c820349c4e9197e.png?1346414267" width="849" height="454"> <img src="http://gyazo.com/9c829fafdf5e58880c820349c4e9197e.png?1346414267" width="849" height="454" />
### pyenv _does..._ ### pyenv _does..._
@ -20,6 +21,7 @@ This project was forked from [rbenv](https://github.com/sstephenson/rbenv) and
* Search commands from **multiple versions of Python at a time**. * Search commands from **multiple versions of Python at a time**.
This may be helpful to test across Python versions with [tox](http://pypi.python.org/pypi/tox). This may be helpful to test across Python versions with [tox](http://pypi.python.org/pypi/tox).
### In contrast with pythonbrew and pythonz, pyenv _does not..._ ### In contrast with pythonbrew and pythonz, pyenv _does not..._
* **Depend on Python itself.** pyenv was made from pure shell scripts. * **Depend on Python itself.** pyenv was made from pure shell scripts.
@ -30,6 +32,7 @@ This project was forked from [rbenv](https://github.com/sstephenson/rbenv) and
yourself, or [pyenv-virtualenv](https://github.com/yyuu/pyenv-virtualenv) yourself, or [pyenv-virtualenv](https://github.com/yyuu/pyenv-virtualenv)
to automate the process. to automate the process.
## Table of Contents ## Table of Contents
* [How It Works](#how-it-works) * [How It Works](#how-it-works)
@ -56,6 +59,7 @@ This project was forked from [rbenv](https://github.com/sstephenson/rbenv) and
* [Version History](#version-history) * [Version History](#version-history)
* [License](#license) * [License](#license)
## How It Works ## How It Works
At a high level, pyenv intercepts Python commands using shim At a high level, pyenv intercepts Python commands using shim
@ -63,6 +67,7 @@ executables injected into your `PATH`, determines which Python version
has been specified by your application, and passes your commands along has been specified by your application, and passes your commands along
to the correct Python installation. to the correct Python installation.
### Understanding PATH ### Understanding PATH
When you run a command like `python` or `pip`, your operating system When you run a command like `python` or `pip`, your operating system
@ -78,6 +83,7 @@ precedence over another one at the end. In this example, the
`/usr/local/bin` directory will be searched first, then `/usr/bin`, `/usr/local/bin` directory will be searched first, then `/usr/bin`,
then `/bin`. then `/bin`.
### Understanding Shims ### Understanding Shims
pyenv works by inserting a directory of _shims_ at the front of your pyenv works by inserting a directory of _shims_ at the front of your
@ -98,28 +104,30 @@ operating system will do the following:
* Run the shim named `pip`, which in turn passes the command along to * Run the shim named `pip`, which in turn passes the command along to
pyenv pyenv
### Choosing the Python Version ### Choosing the Python Version
When you execute a shim, pyenv determines which Python version to use by When you execute a shim, pyenv determines which Python version to use by
reading it from the following sources, in this order: reading it from the following sources, in this order:
1. The `PYENV_VERSION` environment variable, if specified. You can use 1. The `PYENV_VERSION` environment variable (if specified). You can use
the [`pyenv shell`](#pyenv-shell) command to set this environment the [`pyenv shell`](#pyenv-shell) command to set this environment
variable in your current shell session. variable in your current shell session.
2. The application-specific `.python-version` file in the current 2. The application-specific `.python-version` file in the current
directory, if present. You can modify the current directory's directory (if present). You can modify the current directory's
`.python-version` file with the [`pyenv local`](#pyenv-local) `.python-version` file with the [`pyenv local`](#pyenv-local)
command. command.
3. The first `.python-version` file found by searching each parent 3. The first `.python-version` file found (if any) by searching each parent
directory until reaching the root of your filesystem, if any. directory, until reaching the root of your filesystem.
4. The global `~/.pyenv/version` file. You can modify this file using 4. The global `~/.pyenv/version` file. You can modify this file using
the [`pyenv global`](#pyenv-global) command. If the global version the [`pyenv global`](#pyenv-global) command. If the global version
file is not present, pyenv assumes you want to use the "system" file is not present, pyenv assumes you want to use the "system"
Python—i.e. whatever version would be run if pyenv weren't in your Python. (In other words, whatever version would run if pyenv weren't in your
path. `PATH`.)
### Locating the Python Installation ### Locating the Python Installation
@ -128,39 +136,43 @@ specified, it passes the command along to the corresponding Python
installation. installation.
Each Python version is installed into its own directory under Each Python version is installed into its own directory under
`~/.pyenv/versions`. For example, you might have these versions `~/.pyenv/versions`.
installed:
For example, you might have these versions installed:
* `~/.pyenv/versions/2.7.6/` * `~/.pyenv/versions/2.7.6/`
* `~/.pyenv/versions/3.3.3/` * `~/.pyenv/versions/3.3.3/`
* `~/.pyenv/versions/pypy-2.2.1/` * `~/.pyenv/versions/pypy-2.2.1/`
Version names to pyenv are simply the names of the directories in As far as pyenv is concerned, version names are simply the directories in
`~/.pyenv/versions`. `~/.pyenv/versions`.
## Installation ## Installation
If you're on Mac OS X, consider If you're on Mac OS X, consider
[installing with Homebrew](#homebrew-on-mac-os-x). [installing with Homebrew](#homebrew-on-mac-os-x).
### The automatic installer ### The automatic installer
Visit my other project: Visit my other project:
https://github.com/yyuu/pyenv-installer https://github.com/yyuu/pyenv-installer
### Basic GitHub Checkout ### Basic GitHub Checkout
This will get you going with the latest version of pyenv and make it This will get you going with the latest version of pyenv and make it
easy to fork and contribute any changes back upstream. easy to fork and contribute any changes back upstream.
1. Check out pyenv where you want it installed. A good place to choose is 1. **Check out pyenv where you want it installed.** A good place to choose is
`$HOME/.pyenv` but you may install it somewhere else. `$HOME/.pyenv` but you may install it somewhere else.
$ cd $ cd
$ git clone git://github.com/yyuu/pyenv.git .pyenv $ git clone git://github.com/yyuu/pyenv.git .pyenv
2. Define environment variable `PYENV_ROOT` to point to the path where 2. **Define environment variable `PYENV_ROOT`** to point to the path where
pyenv repo is cloned and add `$PYENV_ROOT/bin` to your `$PATH` for access pyenv repo is cloned and add `$PYENV_ROOT/bin` to your `$PATH` for access
to the `pyenv` command-line utility. to the `pyenv` command-line utility.
@ -170,19 +182,19 @@ to the `pyenv` command-line utility.
**Zsh note**: Modify your `~/.zshenv` file instead of `~/.bash_profile`. **Zsh note**: Modify your `~/.zshenv` file instead of `~/.bash_profile`.
**Ubuntu note**: Modify your `~/.bashrc` file instead of `~/.bash_profile`. **Ubuntu note**: Modify your `~/.bashrc` file instead of `~/.bash_profile`.
3. Add pyenv init to your shell to enable shims and autocompletion. 3. **Add `pyenv init` to your shell** to enable shims and autocompletion.
$ echo 'eval "$(pyenv init -)"' >> ~/.bash_profile $ echo 'eval "$(pyenv init -)"' >> ~/.bash_profile
**Zsh note**: Modify your `~/.zshenv` file instead of `~/.bash_profile`. **Zsh note**: Modify your `~/.zshenv` file instead of `~/.bash_profile`.
**Ubuntu note**: Modify your `~/.bashrc` file instead of `~/.bash_profile`. **Ubuntu note**: Modify your `~/.bashrc` file instead of `~/.bash_profile`.
4. Restart your shell so the path changes take effect. You can now 4. **Restart your shell so the path changes take effect.** You can now
begin using pyenv. begin using pyenv.
$ exec $SHELL $ exec $SHELL
5. Install Python versions into `$PYENV_ROOT/versions`. For example, to 5. **Install Python versions into `$PYENV_ROOT/versions`.** For example, to
install Python 2.7.6, download and unpack the source, then run: install Python 2.7.6, download and unpack the source, then run:
$ pyenv install 2.7.6 $ pyenv install 2.7.6
@ -192,12 +204,13 @@ to the `pyenv` command-line utility.
**NOTE** If you are having trouble installing a python version please visit the wiki page about [Common Build Problems](https://github.com/yyuu/pyenv/wiki/Common-build-problems) **NOTE** If you are having trouble installing a python version please visit the wiki page about [Common Build Problems](https://github.com/yyuu/pyenv/wiki/Common-build-problems)
6. Rebuild the shim binaries. You should do this any time you install 6. **Rebuild the shim binaries.** You should do this any time you install
a new Python binary (for example, when installing a new Python version, a new Python binary. (Examples: installing a new Python version,
or when installing a package that provides a binary). or installing a package that provides a binary.)
$ pyenv rehash $ pyenv rehash
#### Upgrading #### Upgrading
If you've installed pyenv using the instructions above, you can If you've installed pyenv using the instructions above, you can
@ -217,23 +230,24 @@ tag:
v0.1.0 v0.1.0
$ git checkout v0.1.0 $ git checkout v0.1.0
### Homebrew on Mac OS X ### Homebrew on Mac OS X
You can also install pyenv using the You can also install pyenv using the
[Homebrew](http://brew.sh) package manager on Mac OS [Homebrew](http://brew.sh) package manager on Mac OS X.
X.
~~~ ~~~
$ brew update $ brew update
$ brew install pyenv $ brew install pyenv
~~~ ~~~
To later update these installs, use `upgrade` instead of `install`. To upgrade pyenv in the future, just use `upgrade` instead of `install`.
Afterwards you'll still need to add `eval "$(pyenv init -)"` to your After installation, you'll still need to add `eval "$(pyenv init -)"` to your
profile as stated in the caveats. You'll only ever have to do this profile (as stated in the caveats). You'll only ever have to do this
once. once.
### Neckbeard Configuration ### Neckbeard Configuration
Skip this section unless you must know what every line in your shell Skip this section unless you must know what every line in your shell
@ -243,47 +257,48 @@ profile is doing.
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. Here's what `pyenv init` actually does:
1. Sets up your shims path. This is the only requirement for pyenv to 1. **Sets up your shims path.** This is the only requirement for pyenv to
function properly. You can do this by hand by prepending function properly. You can do this by hand by prepending
`~/.pyenv/shims` to your `$PATH`. `~/.pyenv/shims` to your `$PATH`.
2. Installs autocompletion. This is entirely optional but pretty 2. **Installs autocompletion.** This is entirely optional but pretty
useful. Sourcing `~/.pyenv/completions/pyenv.bash` will set that useful. Sourcing `~/.pyenv/completions/pyenv.bash` will set that
up. There is also a `~/.pyenv/completions/pyenv.zsh` for Zsh up. There is also a `~/.pyenv/completions/pyenv.zsh` for Zsh
users. users.
3. Rehashes shims. From time to time you'll need to rebuild your 3. **Rehashes shims.** From time to time you'll need to rebuild your
shim files. Doing this on init makes sure everything is up to shim files. Doing this on init makes sure everything is up to
date. You can always run `pyenv rehash` manually. date. You can always run `pyenv rehash` manually.
4. Installs the sh dispatcher. This bit is also optional, but allows 4. **Installs the sh dispatcher.** This bit is also optional, but allows
pyenv and plugins to change variables in your current shell, making pyenv and plugins to change variables in your current shell, making
commands like `pyenv shell` possible. The sh dispatcher doesn't do commands like `pyenv shell` possible. The sh dispatcher doesn't do
anything crazy like override `cd` or hack your shell prompt, but if 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 for some reason you need `pyenv` to be a real script rather than a
shell function, you can safely skip it. shell function, you can safely skip it.
Run `pyenv init -` for yourself to see exactly what happens under the To see exactly what happens under the hood for yourself, run `pyenv init -`.
hood.
### Uninstalling Python Versions ### Uninstalling Python Versions
As time goes on, Python versions you install will accumulate in your As time goes on, you will accumulate Python versions in your
`~/.pyenv/versions` directory. `~/.pyenv/versions` directory.
To remove old Python versions, `pyenv uninstall` command to automate To remove old Python versions, `pyenv uninstall` command to automate
the removal process. the removal process.
Or, simply `rm -rf` the directory of the Alternatively, simply `rm -rf` the directory of the version you want
version you want to remove. You can find the directory of a particular to remove. You can find the directory of a particular Python version
Python version with the `pyenv prefix` command, e.g. `pyenv prefix with the `pyenv prefix` command, e.g. `pyenv prefix 2.6.8`.
2.6.8`.
## Command Reference ## Command Reference
Like `git`, the `pyenv` command delegates to subcommands based on its Like `git`, the `pyenv` command delegates to subcommands based on its
first argument. The most common subcommands are: first argument. The most common subcommands are:
### pyenv local ### pyenv local
Sets a local application-specific Python version by writing the version Sets a local application-specific Python version by writing the version
@ -304,6 +319,7 @@ file named `.pyenv-version`. For backwards compatibility, pyenv will
read a local version specified in an `.pyenv-version` file, but a read a local version specified in an `.pyenv-version` file, but a
`.python-version` file in the same directory will take precedence. `.python-version` file in the same directory will take precedence.
#### pyenv local (advanced) #### pyenv local (advanced)
You can specify multiple versions as local Python at once. You can specify multiple versions as local Python at once.
@ -337,6 +353,7 @@ or, if you prefer 3.3.3 over 2.7.6,
$ python3.3 --version $ python3.3 --version
Python 3.3.3 Python 3.3.3
### pyenv global ### pyenv global
Sets the global version of Python to be used in all shells by writing Sets the global version of Python to be used in all shells by writing
@ -352,6 +369,7 @@ The special version name `system` tells pyenv to use the system Python
When run without a version number, `pyenv global` reports the When run without a version number, `pyenv global` reports the
currently configured global version. currently configured global version.
#### pyenv global (advanced) #### pyenv global (advanced)
You can specify multiple versions as global Python at once. You can specify multiple versions as global Python at once.
@ -385,6 +403,7 @@ or, if you prefer 3.3.3 over 2.7.6,
$ python3.3 --version $ python3.3 --version
Python 3.3.3 Python 3.3.3
### pyenv shell ### pyenv shell
Sets a shell-specific Python version by setting the `PYENV_VERSION` Sets a shell-specific Python version by setting the `PYENV_VERSION`
@ -405,6 +424,7 @@ prefer not to use shell integration, you may simply set the
$ export PYENV_VERSION=pypy-2.2.1 $ export PYENV_VERSION=pypy-2.2.1
#### pyenv shell (advanced) #### pyenv shell (advanced)
You can specify multiple versions via `PYENV_VERSION` at once. You can specify multiple versions via `PYENV_VERSION` at once.
@ -438,6 +458,7 @@ or, if you prefer 3.3.3 over 2.7.6,
$ python3.3 --version $ python3.3 --version
Python 3.3.3 Python 3.3.3
### pyenv versions ### pyenv versions
Lists all Python versions known to pyenv, and shows an asterisk next to Lists all Python versions known to pyenv, and shows an asterisk next to
@ -451,6 +472,7 @@ the currently active version.
jython-2.5.3 jython-2.5.3
pypy-2.2.1 pypy-2.2.1
### pyenv version ### pyenv version
Displays the currently active Python version, along with information on Displays the currently active Python version, along with information on
@ -459,6 +481,7 @@ how it was set.
$ pyenv version $ pyenv version
2.7.6 (set by /home/yyuu/.pyenv/version) 2.7.6 (set by /home/yyuu/.pyenv/version)
### pyenv rehash ### pyenv rehash
Installs shims for all Python binaries known to pyenv (i.e., Installs shims for all Python binaries known to pyenv (i.e.,
@ -467,6 +490,7 @@ version of Python, or install a package that provides binaries.
$ pyenv rehash $ pyenv rehash
### pyenv which ### pyenv which
Displays the full path to the executable that pyenv will invoke when Displays the full path to the executable that pyenv will invoke when
@ -475,6 +499,7 @@ you run the given command.
$ pyenv which python3.3 $ pyenv which python3.3
/home/yyuu/.pyenv/versions/3.3.3/bin/python3.3 /home/yyuu/.pyenv/versions/3.3.3/bin/python3.3
### pyenv whence ### pyenv whence
Lists all Python versions with the given command installed. Lists all Python versions with the given command installed.
@ -484,6 +509,7 @@ Lists all Python versions with the given command installed.
2.7.6 2.7.6
3.3.3 3.3.3
### pyenv install ### pyenv install
Part of [Python-build](https://github.com/yyuu/pyenv/tree/master/plugins/python-build), this installs versions of python Part of [Python-build](https://github.com/yyuu/pyenv/tree/master/plugins/python-build), this installs versions of python
@ -495,6 +521,7 @@ Part of [Python-build](https://github.com/yyuu/pyenv/tree/master/plugins/python-
2.6.8 2.6.8
* 2.7.6 (set by /home/yyuu/.pyenv/version) * 2.7.6 (set by /home/yyuu/.pyenv/version)
### pyenv install --list ### pyenv install --list
List available remote versions of Python, including Anaconda, Jython, pypy, and stackless List available remote versions of Python, including Anaconda, Jython, pypy, and stackless
@ -511,9 +538,10 @@ and easy to understand, even if you're not a shell hacker.
Please feel free to submit pull requests and file bugs on the [issue Please feel free to submit pull requests and file bugs on the [issue
tracker](https://github.com/yyuu/pyenv/issues). tracker](https://github.com/yyuu/pyenv/issues).
### Version History ### Version History
See CHANGELOG.md. See [CHANGELOG.md](CHANGELOG.md).
### License ### License