Hygeia is Python interpreter manager, built with ❤ in Rust. It's goal is to allow individual projects to specify which interpreter to use using a .python-version file.

The previous project's name was pycors.

Python packaging situation is painful. macOS comes with Python 2.7 which is coming close to being end-of-life. Additionally, it does not include pip, the package installer. pip was only included by default with Python >= 3.4.

The install instructions for pip contains a large warning against installing it in the system interpreter.

virtualenv could be used, but it needs to be installed... using pip, resulting in a chicken-and-egg situation.

Hygeia will download and compile specified versions of Python and allow switching between them easily.

The project took a lot of inspiration from pyenv, which does something similar. pyenv is written in Bash though, which prevents it from being used easily on Windows. Hygeia aims to be portable across Windows, Linux and macOS.

Since Python interpreters are downloaded and compiled, some build tools are required.

Make sure dependencies are installed:

1. Homebrew

   ❯ brew install openssl readline sqlite3 xz zlib

2. XCode

   ❯ xcode-select --install

See the Python Developer's Guide for more information.

Please refer to pyenv's wiki for more details.

❯ sudo apt-get update; sudo apt-get install --no-install-recommends make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

❯ yum install gcc zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel openssl-devel tk-devel libffi-devel xz

❯ dnf install make gcc zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel openssl-devel tk-devel libffi-devel xz

pacman -S base-devel openssl zlib

Nothing (expect Hygeia itself) is required to install a Python toolchain under Windows; pre-built binaries are used.

1. Visit the release page to download the latest precompiled version for your platform (Linux, macOS, Windows).
2. Extract to a temporary location.
3. Open a terminal and execute ./hygeia setup <SHELL> (where SHELL is one of bash, zsh or powershell). This will:
   1. copy itself to ${HYGEIA_HOME} (${HOME}/.hygeia) as a shim for Python
   2. create the file ${HYGEIA_HOME}/extra-packages-to-install.txt containing a list of Python packages to pip-install when flag --extra/-e is used with install or select commands
   3. setup ~/.<SHELL>rc to add ${HOME}/.hygeia/shims in the front of your ${PATH}
4. You can delete the downloaded archive and the extracted binary.

As simple as cargo build!

See hygeia --help for all commands:

❯ hygeia --help
hygeia 0.1.4
Nicolas Bigaouette <[email protected]>
Control which Python toolchain to use on a directory basis.

USAGE:
    hygeia [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    autocomplete    Print to stdout an autocomplete script for the specified shell
    help            Prints this message or the help of the given subcommand(s)
    install         Install version, either from the provided version or from `.python-version`
    list            List installed Python versions
    path            Get path to active interpreter
    run             Run a binary from the installed `.python-version`
    select          Select specified Python versions to use
    setup           Setup the shim
    version         Get version of active interpreter

To set up Hygeia by installing it (and its shims) to $HYGEIA_HOME and configuring a bash shell:

❯ hygeia setup bash

This will:

• Copy the hygeia binary to $HYGEIA_HOME/shims/;
• Create hard-links to it with Python binary names;
• Create a bash completion script in $HYGEIA_HOME/hygeia.bash-completion;
• Add $HYGEIA_HOME/shims/ to $PATH through ~/.bashrc;
• Add line sourcing $HYGEIA_HOME/hygeia.bash-completion in ~/.bashrc;
• Create the file $HYGEIA_HOME/extra-packages-to-install.txt containing a list of Python packages to pip-install when flag --extra/-e is used with install or select command.

❯ hygeia list
+--------+---------+------------------------------------------------+
| Active | Version | Location                                       |
+--------+---------+------------------------------------------------+
|        |  3.7.1  | /Users/nbigaouette/.hygeia/installed/3.7.1/bin |
+--------+---------+------------------------------------------------+
|        |  3.7.2  | /Users/nbigaouette/.hygeia/installed/3.7.2/bin |
+--------+---------+------------------------------------------------+
|        |  3.5.6  | /Users/nbigaouette/.hygeia/installed/3.5.6/bin |
+--------+---------+------------------------------------------------+
|   ✓    |  3.6.8  | /Users/nbigaouette/.hygeia/installed/3.6.8/bin |
+--------+---------+------------------------------------------------+
|        |  3.7.2  | /usr/local/bin                                 |
+--------+---------+------------------------------------------------+
|        | 2.7.15  | /usr/local/bin                                 |
+--------+---------+------------------------------------------------+
|        | 2.7.10  | /usr/bin                                       |
+--------+---------+------------------------------------------------+

If the file .python-version contains a version not installed, the list reports it as active but not available:

❯ hygeia list
+--------+---------+------------------------------------------------+
| Active | Version | Location                                       |
+--------+---------+------------------------------------------------+
|   ✗    | = 3.6.8 |                 Not installed                  |
+--------+---------+------------------------------------------------+
|        |  3.7.2  | /usr/local/bin                                 |
+--------+---------+------------------------------------------------+
|        | 2.7.15  | /usr/local/bin                                 |
+--------+---------+------------------------------------------------+
|        | 2.7.10  | /usr/bin                                       |
+--------+---------+------------------------------------------------+

To get the active interpreter's path:

❯ hygeia path
/Users/nbigaouette/.hygeia/installed/3.6.8/bin

To get the active interpreter's version:

❯ hygeia version
3.6.8

This will create (or overwrite) the file .python-version (in the current working directory) with the latest Semantic Versioning version compatible with 3.7.

❯ hygeia select ~3.7
❯ hygeia version
3.7.2

Note that --extra can be used with select or install command to read file $HYGEIA_HOME/extra-packages-to-install.txt and pip install all packages specified. Additionally, --extra-from can also be used to specify a different file. Both flags can be used at the same time and the content of both files will be used. Lines starting with # are ignored (as comments).

The parsing is performed by Rust's semver crate. For details about the parsing, see the Requirements section in the semver crate documentation.

Or simply delete the directory containing the installed interpreter, for example $HYGEIA_HOME/installed/3.5.6 (where $HYGEIA_HOME defaults to $HOME/.hygeia).

Obtain the list of interpreters (and their installed path) using hygeia list.

Export the RUST_LOG environment variable to enable hygeia' log level:

❯ export RUST_LOG=hygeia=debug

See the Rust crates log and env_logger for more information.

Installing a Python package can be done using pip (which will call hygeia' shim).

numpy:

❯ pip install numpy

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

The Rust Code of Conduct shall be respected. For escalation or moderation issues please contact Nicolas ([email protected]) instead of the Rust moderation team.