2012-08-31 06:23:41 +00:00
|
|
|
# Simple Python Version Management: pyenv
|
|
|
|
|
2014-01-08 12:47:36 +00:00
|
|
|
[![Build Status](https://travis-ci.org/yyuu/pyenv.png)](https://travis-ci.org/yyuu/pyenv)
|
|
|
|
|
2012-08-31 06:23:41 +00:00
|
|
|
pyenv lets you easily switch between multiple versions of Python. It's
|
|
|
|
simple, unobtrusive, and follows the UNIX tradition of single-purpose
|
|
|
|
tools that do one thing well.
|
|
|
|
|
2012-09-28 11:17:26 +00:00
|
|
|
This project was forked from [rbenv](https://github.com/sstephenson/rbenv) and
|
|
|
|
[ruby-build](https://github.com/sstephenson/ruby-build), and modified for Python.
|
2012-08-31 06:23:41 +00:00
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
<img src="http://gyazo.com/9c829fafdf5e58880c820349c4e9197e.png?1346414267" width="849" height="454" />
|
|
|
|
|
2012-08-31 11:59:24 +00:00
|
|
|
|
2012-10-03 02:31:10 +00:00
|
|
|
### pyenv _does..._
|
2012-08-31 06:23:41 +00:00
|
|
|
|
|
|
|
* Let you **change the global Python version** on a per-user basis.
|
|
|
|
* Provide support for **per-project Python versions**.
|
|
|
|
* Allow you to **override the Python version** with an environment
|
|
|
|
variable.
|
2012-09-03 10:40:30 +00:00
|
|
|
* Search commands from **multiple versions of Python at a time**.
|
2012-08-31 11:59:24 +00:00
|
|
|
This may be helpful to test across Python versions with [tox](http://pypi.python.org/pypi/tox).
|
2012-08-31 06:23:41 +00:00
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
|
2012-10-03 02:31:10 +00:00
|
|
|
### In contrast with pythonbrew and pythonz, pyenv _does not..._
|
|
|
|
|
2013-08-27 19:27:57 +00:00
|
|
|
* **Depend on Python itself.** pyenv was made from pure shell scripts.
|
2012-10-03 02:31:10 +00:00
|
|
|
There is no bootstrap problem of Python.
|
|
|
|
* **Need to be loaded into your shell.** Instead, pyenv's shim
|
|
|
|
approach works by adding a directory to your `$PATH`.
|
|
|
|
* **Manage virtualenv.** Of course, you can create [virtualenv](http://pypi.python.org/pypi/virtualenv)
|
2013-03-06 03:47:58 +00:00
|
|
|
yourself, or [pyenv-virtualenv](https://github.com/yyuu/pyenv-virtualenv)
|
2012-10-03 02:31:10 +00:00
|
|
|
to automate the process.
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
|
2014-03-20 13:19:11 +00:00
|
|
|
----
|
|
|
|
|
|
|
|
|
2012-08-31 06:23:41 +00:00
|
|
|
## Table of Contents
|
|
|
|
|
2014-03-20 13:17:53 +00:00
|
|
|
* **[How It Works](#how-it-works)**
|
2013-02-06 13:08:16 +00:00
|
|
|
* [Understanding PATH](#understanding-path)
|
|
|
|
* [Understanding Shims](#understanding-shims)
|
|
|
|
* [Choosing the Python Version](#choosing-the-python-version)
|
|
|
|
* [Locating the Python Installation](#locating-the-python-installation)
|
2014-03-20 13:17:53 +00:00
|
|
|
* **[Installation](#installation)**
|
2013-02-06 13:08:16 +00:00
|
|
|
* [Basic GitHub Checkout](#basic-github-checkout)
|
|
|
|
* [Upgrading](#upgrading)
|
2013-06-13 11:04:37 +00:00
|
|
|
* [Homebrew on Mac OS X](#homebrew-on-mac-os-x)
|
2013-02-06 13:08:16 +00:00
|
|
|
* [Neckbeard Configuration](#neckbeard-configuration)
|
|
|
|
* [Uninstalling Python Versions](#uninstalling-python-versions)
|
2014-03-20 13:17:53 +00:00
|
|
|
* **[Command Reference](#command-reference)**
|
|
|
|
* **[Development](#development)**
|
2013-02-06 13:08:16 +00:00
|
|
|
* [Version History](#version-history)
|
|
|
|
* [License](#license)
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
|
2014-03-20 13:19:11 +00:00
|
|
|
----
|
|
|
|
|
|
|
|
|
2013-02-06 13:08:16 +00:00
|
|
|
## How It Works
|
|
|
|
|
|
|
|
At a high level, pyenv intercepts Python commands using shim
|
|
|
|
executables injected into your `PATH`, determines which Python version
|
|
|
|
has been specified by your application, and passes your commands along
|
|
|
|
to the correct Python installation.
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
|
2013-02-06 13:08:16 +00:00
|
|
|
### Understanding PATH
|
|
|
|
|
|
|
|
When you run a command like `python` or `pip`, your operating system
|
|
|
|
searches through a list of directories to find an executable file with
|
|
|
|
that name. This list of directories lives in an environment variable
|
|
|
|
called `PATH`, with each directory in the list separated by a colon:
|
|
|
|
|
|
|
|
/usr/local/bin:/usr/bin:/bin
|
|
|
|
|
|
|
|
Directories in `PATH` are searched from left to right, so a matching
|
|
|
|
executable in a directory at the beginning of the list takes
|
|
|
|
precedence over another one at the end. In this example, the
|
|
|
|
`/usr/local/bin` directory will be searched first, then `/usr/bin`,
|
|
|
|
then `/bin`.
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
|
2013-02-06 13:08:16 +00:00
|
|
|
### Understanding Shims
|
|
|
|
|
|
|
|
pyenv works by inserting a directory of _shims_ at the front of your
|
|
|
|
`PATH`:
|
|
|
|
|
|
|
|
~/.pyenv/shims:/usr/local/bin:/usr/bin:/bin
|
|
|
|
|
|
|
|
Through a process called _rehashing_, pyenv maintains shims in that
|
|
|
|
directory to match every Python command across every installed version
|
|
|
|
of Python—`python`, `pip`, and so on.
|
|
|
|
|
|
|
|
Shims are lightweight executables that simply pass your command along
|
|
|
|
to pyenv. So with pyenv installed, when you run, say, `pip`, your
|
|
|
|
operating system will do the following:
|
|
|
|
|
|
|
|
* Search your `PATH` for an executable file named `pip`
|
|
|
|
* Find the pyenv shim named `pip` at the beginning of your `PATH`
|
|
|
|
* Run the shim named `pip`, which in turn passes the command along to
|
|
|
|
pyenv
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
|
2013-02-06 13:08:16 +00:00
|
|
|
### Choosing the Python Version
|
|
|
|
|
|
|
|
When you execute a shim, pyenv determines which Python version to use by
|
|
|
|
reading it from the following sources, in this order:
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
1. The `PYENV_VERSION` environment variable (if specified). You can use
|
2013-02-06 13:08:16 +00:00
|
|
|
the [`pyenv shell`](#pyenv-shell) command to set this environment
|
|
|
|
variable in your current shell session.
|
|
|
|
|
|
|
|
2. The application-specific `.python-version` file in the current
|
2014-03-19 19:00:54 +00:00
|
|
|
directory (if present). You can modify the current directory's
|
2013-02-06 13:08:16 +00:00
|
|
|
`.python-version` file with the [`pyenv local`](#pyenv-local)
|
|
|
|
command.
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
3. The first `.python-version` file found (if any) by searching each parent
|
|
|
|
directory, until reaching the root of your filesystem.
|
2013-02-06 13:08:16 +00:00
|
|
|
|
|
|
|
4. The global `~/.pyenv/version` file. You can modify this file using
|
|
|
|
the [`pyenv global`](#pyenv-global) command. If the global version
|
|
|
|
file is not present, pyenv assumes you want to use the "system"
|
2014-03-19 19:00:54 +00:00
|
|
|
Python. (In other words, whatever version would run if pyenv weren't in your
|
|
|
|
`PATH`.)
|
|
|
|
|
2013-02-06 13:08:16 +00:00
|
|
|
|
|
|
|
### Locating the Python Installation
|
|
|
|
|
|
|
|
Once pyenv has determined which version of Python your application has
|
|
|
|
specified, it passes the command along to the corresponding Python
|
|
|
|
installation.
|
|
|
|
|
|
|
|
Each Python version is installed into its own directory under
|
2014-03-19 19:00:54 +00:00
|
|
|
`~/.pyenv/versions`.
|
|
|
|
|
|
|
|
For example, you might have these versions installed:
|
2013-02-06 13:08:16 +00:00
|
|
|
|
2014-01-29 08:54:01 +00:00
|
|
|
* `~/.pyenv/versions/2.7.6/`
|
|
|
|
* `~/.pyenv/versions/3.3.3/`
|
|
|
|
* `~/.pyenv/versions/pypy-2.2.1/`
|
2013-02-06 13:08:16 +00:00
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
As far as pyenv is concerned, version names are simply the directories in
|
2013-02-06 13:08:16 +00:00
|
|
|
`~/.pyenv/versions`.
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
|
2014-03-20 13:19:11 +00:00
|
|
|
----
|
|
|
|
|
|
|
|
|
2013-02-06 13:08:16 +00:00
|
|
|
## Installation
|
|
|
|
|
2014-03-20 13:17:53 +00:00
|
|
|
If you're on Mac OS X, consider [installing with Homebrew](#homebrew-on-mac-os-x).
|
2013-06-13 11:04:37 +00:00
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
|
2014-02-21 03:57:42 +00:00
|
|
|
### The automatic installer
|
|
|
|
|
|
|
|
Visit my other project:
|
|
|
|
https://github.com/yyuu/pyenv-installer
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
|
2013-02-06 13:08:16 +00:00
|
|
|
### Basic GitHub Checkout
|
2012-08-31 06:23:41 +00:00
|
|
|
|
|
|
|
This will get you going with the latest version of pyenv and make it
|
|
|
|
easy to fork and contribute any changes back upstream.
|
|
|
|
|
2014-03-20 13:17:53 +00:00
|
|
|
1. **Check out pyenv where you want it installed.**
|
|
|
|
A good place to choose is `$HOME/.pyenv` (but you can install it somewhere else).
|
2012-08-31 06:23:41 +00:00
|
|
|
|
|
|
|
$ cd
|
|
|
|
$ git clone git://github.com/yyuu/pyenv.git .pyenv
|
|
|
|
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
2. **Define environment variable `PYENV_ROOT`** to point to the path where
|
2014-03-20 13:17:53 +00:00
|
|
|
pyenv repo is cloned and add `$PYENV_ROOT/bin` to your `$PATH` for access
|
|
|
|
to the `pyenv` command-line utility.
|
2013-08-28 06:33:18 +00:00
|
|
|
|
|
|
|
$ echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile
|
|
|
|
$ echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile
|
2012-08-31 06:23:41 +00:00
|
|
|
|
|
|
|
**Zsh note**: Modify your `~/.zshenv` file instead of `~/.bash_profile`.
|
2013-09-13 00:07:40 +00:00
|
|
|
**Ubuntu note**: Modify your `~/.bashrc` file instead of `~/.bash_profile`.
|
2012-08-31 06:23:41 +00:00
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
3. **Add `pyenv init` to your shell** to enable shims and autocompletion.
|
2012-08-31 06:23:41 +00:00
|
|
|
|
|
|
|
$ echo 'eval "$(pyenv init -)"' >> ~/.bash_profile
|
|
|
|
|
|
|
|
**Zsh note**: Modify your `~/.zshenv` file instead of `~/.bash_profile`.
|
2013-09-13 00:07:40 +00:00
|
|
|
**Ubuntu note**: Modify your `~/.bashrc` file instead of `~/.bash_profile`.
|
2012-08-31 06:23:41 +00:00
|
|
|
|
2014-03-20 13:17:53 +00:00
|
|
|
4. **Restart your shell so the path changes take effect.**
|
|
|
|
You can now begin using pyenv.
|
2012-08-31 06:23:41 +00:00
|
|
|
|
|
|
|
$ exec $SHELL
|
|
|
|
|
2014-03-20 13:17:53 +00:00
|
|
|
5. **Install Python versions into `$PYENV_ROOT/versions`.**
|
|
|
|
For example, to install Python 2.7.6, download and unpack the source, then run:
|
2012-08-31 06:23:41 +00:00
|
|
|
|
2014-01-29 08:54:01 +00:00
|
|
|
$ pyenv install 2.7.6
|
2013-05-16 14:24:21 +00:00
|
|
|
|
2014-03-20 13:17:53 +00:00
|
|
|
**NOTE:** If you need to pass configure option to build, please use
|
2013-05-16 14:24:21 +00:00
|
|
|
```CONFIGURE_OPTS``` environment variable.
|
2013-11-20 16:16:03 +00:00
|
|
|
|
2014-03-20 13:17:53 +00:00
|
|
|
**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)
|
2012-08-31 06:23:41 +00:00
|
|
|
|
2014-03-20 13:17:53 +00:00
|
|
|
6. **Rebuild the shim binaries.**
|
|
|
|
You should do this any time you install a new Python binary.
|
|
|
|
(Examples: installing a new Python version, or installing a package that provides a binary.)
|
2012-08-31 06:23:41 +00:00
|
|
|
|
|
|
|
$ pyenv rehash
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
|
2013-02-06 13:08:16 +00:00
|
|
|
#### Upgrading
|
2012-08-31 06:23:41 +00:00
|
|
|
|
|
|
|
If you've installed pyenv using the instructions above, you can
|
|
|
|
upgrade your installation at any time using git.
|
|
|
|
|
|
|
|
To upgrade to the latest development version of pyenv, use `git pull`:
|
|
|
|
|
|
|
|
$ cd ~/.pyenv
|
|
|
|
$ git pull
|
|
|
|
|
2014-03-20 13:17:53 +00:00
|
|
|
To upgrade to a specific release of pyenv, check out the corresponding tag:
|
2012-08-31 06:23:41 +00:00
|
|
|
|
|
|
|
$ cd ~/.pyenv
|
|
|
|
$ git fetch
|
|
|
|
$ git tag
|
|
|
|
v0.1.0
|
2012-08-31 11:59:24 +00:00
|
|
|
$ git checkout v0.1.0
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
|
2013-06-13 11:04:37 +00:00
|
|
|
### Homebrew on Mac OS X
|
|
|
|
|
2014-03-20 13:17:53 +00:00
|
|
|
You can also install pyenv using the [Homebrew](http://brew.sh)
|
|
|
|
package manager for Mac OS X.
|
|
|
|
|
|
|
|
$ brew update
|
|
|
|
$ brew install pyenv
|
2013-06-13 11:04:37 +00:00
|
|
|
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
To upgrade pyenv in the future, just use `upgrade` instead of `install`.
|
2013-06-13 11:04:37 +00:00
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
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
|
2013-06-13 11:04:37 +00:00
|
|
|
once.
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
|
2013-02-06 13:08:16 +00:00
|
|
|
### Neckbeard Configuration
|
2012-08-31 11:59:24 +00:00
|
|
|
|
|
|
|
Skip this section unless you must know what every line in your shell
|
|
|
|
profile is doing.
|
|
|
|
|
|
|
|
`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
|
|
|
|
opposed to this idea. Here's what `pyenv init` actually does:
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
1. **Sets up your shims path.** This is the only requirement for pyenv to
|
2012-08-31 11:59:24 +00:00
|
|
|
function properly. You can do this by hand by prepending
|
|
|
|
`~/.pyenv/shims` to your `$PATH`.
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
2. **Installs autocompletion.** This is entirely optional but pretty
|
2012-08-31 11:59:24 +00:00
|
|
|
useful. Sourcing `~/.pyenv/completions/pyenv.bash` will set that
|
|
|
|
up. There is also a `~/.pyenv/completions/pyenv.zsh` for Zsh
|
|
|
|
users.
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
3. **Rehashes shims.** From time to time you'll need to rebuild your
|
2012-08-31 11:59:24 +00:00
|
|
|
shim files. Doing this on init makes sure everything is up to
|
|
|
|
date. You can always run `pyenv rehash` manually.
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
4. **Installs the sh dispatcher.** This bit is also optional, but allows
|
2012-08-31 11:59:24 +00:00
|
|
|
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.
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
To see exactly what happens under the hood for yourself, run `pyenv init -`.
|
|
|
|
|
2012-08-31 06:23:41 +00:00
|
|
|
|
2013-02-06 13:08:16 +00:00
|
|
|
### Uninstalling Python Versions
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
As time goes on, you will accumulate Python versions in your
|
2013-02-06 13:08:16 +00:00
|
|
|
`~/.pyenv/versions` directory.
|
|
|
|
|
|
|
|
To remove old Python versions, `pyenv uninstall` command to automate
|
|
|
|
the removal process.
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
Alternatively, simply `rm -rf` the directory of the version you want
|
|
|
|
to remove. You can find the directory of a particular Python version
|
|
|
|
with the `pyenv prefix` command, e.g. `pyenv prefix 2.6.8`.
|
|
|
|
|
2013-02-06 13:08:16 +00:00
|
|
|
|
2014-03-20 13:19:11 +00:00
|
|
|
----
|
|
|
|
|
|
|
|
|
2013-02-06 13:08:16 +00:00
|
|
|
## Command Reference
|
2012-08-31 06:23:41 +00:00
|
|
|
|
2014-03-20 13:13:15 +00:00
|
|
|
See [COMMANDS.md](COMMANDS.md).
|
2014-03-03 22:11:23 +00:00
|
|
|
|
2012-08-31 11:59:24 +00:00
|
|
|
|
2014-03-20 13:19:11 +00:00
|
|
|
----
|
|
|
|
|
|
|
|
|
2013-02-06 13:08:16 +00:00
|
|
|
## Development
|
2012-08-31 06:23:41 +00:00
|
|
|
|
2014-03-20 13:17:53 +00:00
|
|
|
The pyenv source code is [hosted on GitHub](https://github.com/yyuu/pyenv).
|
|
|
|
It's clean, modular, and easy to understand--even if you're not a shell hacker.
|
2012-08-31 06:23:41 +00:00
|
|
|
|
2014-03-20 13:17:53 +00:00
|
|
|
Please feel free to submit Pull Requests and report bugs on the
|
|
|
|
[issue tracker](https://github.com/yyuu/pyenv/issues).
|
2012-08-31 06:23:41 +00:00
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
|
2013-02-06 13:08:16 +00:00
|
|
|
### Version History
|
|
|
|
|
2014-03-19 19:00:54 +00:00
|
|
|
See [CHANGELOG.md](CHANGELOG.md).
|
2013-02-06 13:08:16 +00:00
|
|
|
|
2012-08-31 06:23:41 +00:00
|
|
|
|
2013-02-06 13:08:16 +00:00
|
|
|
### License
|
2012-08-31 06:23:41 +00:00
|
|
|
|
|
|
|
(The MIT license)
|
|
|
|
|
2013-02-23 10:06:58 +00:00
|
|
|
* Copyright (c) 2013 Yamashita, Yuu
|
|
|
|
* Copyright (c) 2013 Sam Stephenson
|
2012-08-31 06:23:41 +00:00
|
|
|
|
|
|
|
Permission is hereby granted, free of charge, to any person obtaining
|
|
|
|
a copy of this software and associated documentation files (the
|
|
|
|
"Software"), to deal in the Software without restriction, including
|
|
|
|
without limitation the rights to use, copy, modify, merge, publish,
|
|
|
|
distribute, sublicense, and/or sell copies of the Software, and to
|
|
|
|
permit persons to whom the Software is furnished to do so, subject to
|
|
|
|
the following conditions:
|
|
|
|
|
|
|
|
The above copyright notice and this permission notice shall be
|
|
|
|
included in all copies or substantial portions of the Software.
|
|
|
|
|
|
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
|
|
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
|
|
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
|
|
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
|
|
|
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
|
|
|
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
|
|
|
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|