Merge pull request #141 from Zearin/docs

Updated README.md; Commands moved to COMMANDS.md.
This commit is contained in:
Yamashita, Yuu 2014-03-22 15:58:31 +09:00
commit d75e12298a
2 changed files with 330 additions and 270 deletions

286
COMMANDS.md Normal file
View file

@ -0,0 +1,286 @@
# Command Reference
Like `git`, the `pyenv` command delegates to subcommands based on its
first argument.
The most common subcommands are:
* [`pyenv commands`](#pyenv-commands)
* [`pyenv local`](#pyenv-local)
* [`pyenv global`](#pyenv-global)
* [`pyenv shell`](#pyenv-shell)
* [`pyenv install`](#pyenv-install)
* [`pyenv uninstall`](#pyenv-uninstall)
* [`pyenv rehash`](#pyenv-rehash)
* [`pyenv version`](#pyenv-version)
* [`pyenv versions`](#pyenv-versions)
* [`pyenv which`](#pyenv-which)
* [`pyenv whence`](#pyenv-whence)
## `pyenv commands`
Lists all available pyenv commands.
## `pyenv local`
Sets a local application-specific Python version by writing the version
name to a `.python-version` file in the current directory. This version
overrides the global version, and can be overridden itself by setting
the `PYENV_VERSION` environment variable or with the `pyenv shell`
command.
$ pyenv local 2.7.6
When run without a version number, `pyenv local` reports the currently
configured local version. You can also unset the local version:
$ pyenv local --unset
Previous versions of pyenv stored local version specifications in a
file named `.pyenv-version`. For backwards compatibility, pyenv will
read a local version specified in an `.pyenv-version` file, but a
`.python-version` file in the same directory will take precedence.
### `pyenv local` (advanced)
You can specify multiple versions as local Python at once.
Let's say if you have two versions of 2.7.6 and 3.3.3. If you prefer 2.7.6 over 3.3.3,
$ pyenv local 2.7.6 3.3.3
$ pyenv versions
system
* 2.7.6 (set by /Users/yyuu/path/to/project/.python-version)
* 3.3.3 (set by /Users/yyuu/path/to/project/.python-version)
$ python --version
Python 2.7.6
$ python2.7 --version
Python 2.7.6
$ python3.3 --version
Python 3.3.3
or, if you prefer 3.3.3 over 2.7.6,
$ pyenv local 3.3.3 2.7.6
$ pyenv versions
system
* 2.7.6 (set by /Users/yyuu/path/to/project/.python-version)
* 3.3.3 (set by /Users/yyuu/path/to/project/.python-version)
venv27
$ python --version
Python 3.3.3
$ python2.7 --version
Python 2.7.6
$ python3.3 --version
Python 3.3.3
## `pyenv global`
Sets the global version of Python to be used in all shells by writing
the version name to the `~/.pyenv/version` file. This version can be
overridden by an application-specific `.python-version` file, or by
setting the `PYENV_VERSION` environment variable.
$ pyenv global 2.7.6
The special version name `system` tells pyenv to use the system Python
(detected by searching your `$PATH`).
When run without a version number, `pyenv global` reports the
currently configured global version.
### `pyenv global` (advanced)
You can specify multiple versions as global Python at once.
Let's say if you have two versions of 2.7.6 and 3.3.3. If you prefer 2.7.6 over 3.3.3,
$ pyenv global 2.7.6 3.3.3
$ pyenv versions
system
* 2.7.6 (set by /Users/yyuu/.pyenv/version)
* 3.3.3 (set by /Users/yyuu/.pyenv/version)
$ python --version
Python 2.7.6
$ python2.7 --version
Python 2.7.6
$ python3.3 --version
Python 3.3.3
or, if you prefer 3.3.3 over 2.7.6,
$ pyenv global 3.3.3 2.7.6
$ pyenv versions
system
* 2.7.6 (set by /Users/yyuu/.pyenv/version)
* 3.3.3 (set by /Users/yyuu/.pyenv/version)
venv27
$ python --version
Python 3.3.3
$ python2.7 --version
Python 2.7.6
$ python3.3 --version
Python 3.3.3
## `pyenv shell`
Sets a shell-specific Python version by setting the `PYENV_VERSION`
environment variable in your shell. This version overrides
application-specific versions and the global version.
$ pyenv shell pypy-2.2.1
When run without a version number, `pyenv shell` reports the current
value of `PYENV_VERSION`. You can also unset the shell version:
$ pyenv shell --unset
Note that you'll need pyenv's shell integration enabled (step 3 of
the installation instructions) in order to use this command. If you
prefer not to use shell integration, you may simply set the
`PYENV_VERSION` variable yourself:
$ export PYENV_VERSION=pypy-2.2.1
### `pyenv shell` (advanced)
You can specify multiple versions via `PYENV_VERSION` at once.
Let's say if you have two versions of 2.7.6 and 3.3.3. If you prefer 2.7.6 over 3.3.3,
$ pyenv shell 2.7.6 3.3.3
$ pyenv versions
system
* 2.7.6 (set by PYENV_VERSION environment variable)
* 3.3.3 (set by PYENV_VERSION environment variable)
$ python --version
Python 2.7.6
$ python2.7 --version
Python 2.7.6
$ python3.3 --version
Python 3.3.3
or, if you prefer 3.3.3 over 2.7.6,
$ pyenv shell 3.3.3 2.7.6
$ pyenv versions
system
* 2.7.6 (set by PYENV_VERSION environment variable)
* 3.3.3 (set by PYENV_VERSION environment variable)
venv27
$ python --version
Python 3.3.3
$ python2.7 --version
Python 2.7.6
$ python3.3 --version
Python 3.3.3
## `pyenv install`
Install a Python version (using `python-build`).
Usage: pyenv install [-f] [-kvp] <version>
pyenv install [-f] [-kvp] <definition-file>
pyenv install -l|--list
-l/--list List all available versions
-f/--force Install even if the version appears to be installed already
python-build options:
-k/--keep Keep source tree in $PYENV_BUILD_ROOT after installation
(defaults to $PYENV_ROOT/sources)
-v/--verbose Verbose mode: print compilation status to stdout
-p/--patch Apply a patch from stdin before building
-g/--debug Build a debug version
## `pyenv uninstall`
Uninstall a specific Python version.
Usage: pyenv uninstall [-f|--force] <version>
-f Attempt to remove the specified version without prompting
for confirmation. If the version does not exist, do not
display an error message.
## `pyenv rehash`
Installs shims for all Python binaries known to pyenv (i.e.,
`~/.pyenv/versions/*/bin/*`). Run this command after you install a new
version of Python, or install a package that provides binaries.
$ pyenv rehash
## `pyenv version`
Displays the currently active Python version, along with information on
how it was set.
$ pyenv version
2.7.6 (set by /home/yyuu/.pyenv/version)
## `pyenv versions`
Lists all Python versions known to pyenv, and shows an asterisk next to
the currently active version.
$ pyenv versions
2.5.6
2.6.8
* 2.7.6 (set by /home/yyuu/.pyenv/version)
3.3.3
jython-2.5.3
pypy-2.2.1
## `pyenv which`
Displays the full path to the executable that pyenv will invoke when
you run the given command.
$ pyenv which python3.3
/home/yyuu/.pyenv/versions/3.3.3/bin/python3.3
## `pyenv whence`
Lists all Python versions with the given command installed.
$ pyenv whence 2to3
2.6.8
2.7.6
3.3.3
## `pyenv install`
Part of [Python-build](https://github.com/yyuu/pyenv/tree/master/plugins/python-build), this installs versions of python
$ pyenv install 2.7.6
$ pyenv install 2.6.8
$ pyenv versions
system
2.6.8
* 2.7.6 (set by /home/yyuu/.pyenv/version)
## `pyenv install --list`
List available remote versions of Python, including Anaconda, Jython, pypy, and stackless
$ pyenv install --list

314
README.md
View file

@ -33,33 +33,31 @@ This project was forked from [rbenv](https://github.com/sstephenson/rbenv) and
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)**
* [Understanding PATH](#understanding-path) * [Understanding PATH](#understanding-path)
* [Understanding Shims](#understanding-shims) * [Understanding Shims](#understanding-shims)
* [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)**
* [Basic GitHub Checkout](#basic-github-checkout) * [Basic GitHub Checkout](#basic-github-checkout)
* [Upgrading](#upgrading) * [Upgrading](#upgrading)
* [Homebrew on Mac OS X](#homebrew-on-mac-os-x) * [Homebrew on Mac OS X](#homebrew-on-mac-os-x)
* [Neckbeard Configuration](#neckbeard-configuration) * [Neckbeard Configuration](#neckbeard-configuration)
* [Uninstalling Python Versions](#uninstalling-python-versions) * [Uninstalling Python Versions](#uninstalling-python-versions)
* [Command Reference](#command-reference) * **[Command Reference](#command-reference)**
* [pyenv local](#pyenv-local) * **[Development](#development)**
* [pyenv global](#pyenv-global)
* [pyenv shell](#pyenv-shell)
* [pyenv versions](#pyenv-versions)
* [pyenv version](#pyenv-version)
* [pyenv rehash](#pyenv-rehash)
* [pyenv which](#pyenv-which)
* [pyenv whence](#pyenv-whence)
* [Development](#development)
* [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
@ -148,10 +146,12 @@ 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
@ -165,16 +165,16 @@ https://github.com/yyuu/pyenv-installer
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.**
`$HOME/.pyenv` but you may install it somewhere else. A good place to choose is `$HOME/.pyenv` (but you can 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.
$ echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile $ echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile
$ echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile $ echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile
@ -189,24 +189,26 @@ 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`.
4. **Restart your shell so the path changes take effect.** You can now 4. **Restart your shell so the path changes take effect.**
begin using pyenv. You can now 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`.**
install Python 2.7.6, download and unpack the source, then run: For example, to install Python 2.7.6, download and unpack the source, then run:
$ pyenv install 2.7.6 $ pyenv install 2.7.6
**NOTE** If you need to pass configure option to build, please use **NOTE:** If you need to pass configure option to build, please use
```CONFIGURE_OPTS``` environment variable. ```CONFIGURE_OPTS``` environment variable.
**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.**
a new Python binary. (Examples: installing a new Python version, You should do this any time you install a new Python binary.
or installing a package that provides a binary.) (Examples: installing a new Python version, or installing a package that provides a binary.)
$ pyenv rehash $ pyenv rehash
@ -221,8 +223,7 @@ To upgrade to the latest development version of pyenv, use `git pull`:
$ cd ~/.pyenv $ cd ~/.pyenv
$ git pull $ git pull
To upgrade to a specific release of pyenv, check out the corresponding To upgrade to a specific release of pyenv, check out the corresponding tag:
tag:
$ cd ~/.pyenv $ cd ~/.pyenv
$ git fetch $ git fetch
@ -233,13 +234,12 @@ tag:
### 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)
[Homebrew](http://brew.sh) package manager on Mac OS X. package manager for Mac OS X.
$ brew update
$ brew install pyenv
~~~
$ brew update
$ brew install pyenv
~~~
To upgrade pyenv in the future, just use `upgrade` instead of `install`. To upgrade pyenv in the future, just use `upgrade` instead of `install`.
@ -293,250 +293,24 @@ to remove. You can find the directory of a particular Python version
with the `pyenv prefix` command, e.g. `pyenv prefix 2.6.8`. with the `pyenv prefix` command, e.g. `pyenv prefix 2.6.8`.
----
## Command Reference ## Command Reference
Like `git`, the `pyenv` command delegates to subcommands based on its See [COMMANDS.md](COMMANDS.md).
first argument. The most common subcommands are:
### pyenv local ----
Sets a local application-specific Python version by writing the version
name to a `.python-version` file in the current directory. This version
overrides the global version, and can be overridden itself by setting
the `PYENV_VERSION` environment variable or with the `pyenv shell`
command.
$ pyenv local 2.7.6
When run without a version number, `pyenv local` reports the currently
configured local version. You can also unset the local version:
$ pyenv local --unset
Previous versions of pyenv stored local version specifications in a
file named `.pyenv-version`. For backwards compatibility, pyenv will
read a local version specified in an `.pyenv-version` file, but a
`.python-version` file in the same directory will take precedence.
#### pyenv local (advanced)
You can specify multiple versions as local Python at once.
Let's say if you have two versions of 2.7.6 and 3.3.3. If you prefer 2.7.6 over 3.3.3,
$ pyenv local 2.7.6 3.3.3
$ pyenv versions
system
* 2.7.6 (set by /Users/yyuu/path/to/project/.python-version)
* 3.3.3 (set by /Users/yyuu/path/to/project/.python-version)
$ python --version
Python 2.7.6
$ python2.7 --version
Python 2.7.6
$ python3.3 --version
Python 3.3.3
or, if you prefer 3.3.3 over 2.7.6,
$ pyenv local 3.3.3 2.7.6
$ pyenv versions
system
* 2.7.6 (set by /Users/yyuu/path/to/project/.python-version)
* 3.3.3 (set by /Users/yyuu/path/to/project/.python-version)
venv27
$ python --version
Python 3.3.3
$ python2.7 --version
Python 2.7.6
$ python3.3 --version
Python 3.3.3
### pyenv global
Sets the global version of Python to be used in all shells by writing
the version name to the `~/.pyenv/version` file. This version can be
overridden by an application-specific `.python-version` file, or by
setting the `PYENV_VERSION` environment variable.
$ pyenv global 2.7.6
The special version name `system` tells pyenv to use the system Python
(detected by searching your `$PATH`).
When run without a version number, `pyenv global` reports the
currently configured global version.
#### pyenv global (advanced)
You can specify multiple versions as global Python at once.
Let's say if you have two versions of 2.7.6 and 3.3.3. If you prefer 2.7.6 over 3.3.3,
$ pyenv global 2.7.6 3.3.3
$ pyenv versions
system
* 2.7.6 (set by /Users/yyuu/.pyenv/version)
* 3.3.3 (set by /Users/yyuu/.pyenv/version)
$ python --version
Python 2.7.6
$ python2.7 --version
Python 2.7.6
$ python3.3 --version
Python 3.3.3
or, if you prefer 3.3.3 over 2.7.6,
$ pyenv global 3.3.3 2.7.6
$ pyenv versions
system
* 2.7.6 (set by /Users/yyuu/.pyenv/version)
* 3.3.3 (set by /Users/yyuu/.pyenv/version)
venv27
$ python --version
Python 3.3.3
$ python2.7 --version
Python 2.7.6
$ python3.3 --version
Python 3.3.3
### pyenv shell
Sets a shell-specific Python version by setting the `PYENV_VERSION`
environment variable in your shell. This version overrides
application-specific versions and the global version.
$ pyenv shell pypy-2.2.1
When run without a version number, `pyenv shell` reports the current
value of `PYENV_VERSION`. You can also unset the shell version:
$ pyenv shell --unset
Note that you'll need pyenv's shell integration enabled (step 3 of
the installation instructions) in order to use this command. If you
prefer not to use shell integration, you may simply set the
`PYENV_VERSION` variable yourself:
$ export PYENV_VERSION=pypy-2.2.1
#### pyenv shell (advanced)
You can specify multiple versions via `PYENV_VERSION` at once.
Let's say if you have two versions of 2.7.6 and 3.3.3. If you prefer 2.7.6 over 3.3.3,
$ pyenv shell 2.7.6 3.3.3
$ pyenv versions
system
* 2.7.6 (set by PYENV_VERSION environment variable)
* 3.3.3 (set by PYENV_VERSION environment variable)
$ python --version
Python 2.7.6
$ python2.7 --version
Python 2.7.6
$ python3.3 --version
Python 3.3.3
or, if you prefer 3.3.3 over 2.7.6,
$ pyenv shell 3.3.3 2.7.6
$ pyenv versions
system
* 2.7.6 (set by PYENV_VERSION environment variable)
* 3.3.3 (set by PYENV_VERSION environment variable)
venv27
$ python --version
Python 3.3.3
$ python2.7 --version
Python 2.7.6
$ python3.3 --version
Python 3.3.3
### pyenv versions
Lists all Python versions known to pyenv, and shows an asterisk next to
the currently active version.
$ pyenv versions
2.5.6
2.6.8
* 2.7.6 (set by /home/yyuu/.pyenv/version)
3.3.3
jython-2.5.3
pypy-2.2.1
### pyenv version
Displays the currently active Python version, along with information on
how it was set.
$ pyenv version
2.7.6 (set by /home/yyuu/.pyenv/version)
### pyenv rehash
Installs shims for all Python binaries known to pyenv (i.e.,
`~/.pyenv/versions/*/bin/*`). Run this command after you install a new
version of Python, or install a package that provides binaries.
$ pyenv rehash
### pyenv which
Displays the full path to the executable that pyenv will invoke when
you run the given command.
$ pyenv which python3.3
/home/yyuu/.pyenv/versions/3.3.3/bin/python3.3
### pyenv whence
Lists all Python versions with the given command installed.
$ pyenv whence 2to3
2.6.8
2.7.6
3.3.3
### pyenv install
Part of [Python-build](https://github.com/yyuu/pyenv/tree/master/plugins/python-build), this installs versions of python
$ pyenv install 2.7.6
$ pyenv install 2.6.8
$ pyenv versions
system
2.6.8
* 2.7.6 (set by /home/yyuu/.pyenv/version)
### pyenv install --list
List available remote versions of Python, including Anaconda, Jython, pypy, and stackless
$ pyenv install --list
## Development ## Development
The pyenv source code is [hosted on The pyenv source code is [hosted on GitHub](https://github.com/yyuu/pyenv).
GitHub](https://github.com/yyuu/pyenv). It's clean, modular, It's clean, modular, and easy to understand--even if you're not a shell hacker.
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 report bugs on the
tracker](https://github.com/yyuu/pyenv/issues). [issue tracker](https://github.com/yyuu/pyenv/issues).
### Version History ### Version History