Getting Started with pyenv: A Must-Have Tool for Python Development

What is pyenv, and Why Do You Need It?

pyenv is a simple yet powerful tool that allows you to manage multiple Python versions on your system. As a Python developer, you often need to work on different projects that require different Python versions. Manually managing these versions can be cumbersome and prone to errors. This is where pyenv comes in, making it easy to switch between Python versions, ensuring that your projects are always running on the correct version.

Why Use pyenv?

• Version Management: Install and switch between different Python versions effortlessly.

• Project Isolation: Ensure that each project uses the correct Python version, avoiding compatibility issues.

• Flexibility: Easily test your code on multiple Python versions.

If you've ever faced issues with version conflicts or had to work with both Python 2.x and 3.x on the same machine, you'll appreciate how pyenv simplifies your development workflow.

Integrating pyenv with Poetry

pyenv works exceptionally well with Poetry, a tool that manages dependencies and Python environments. If you're already familiar with Poetry (and if you aren't, check out my article on getting started with Poetry), you'll find that combining it with pyenv gives you even more control over your projects.

When you create a new project with Poetry, it automatically uses the Python version that pyenv has set for the directory. This ensures that your project dependencies are managed in an environment that matches your project's requirements.

Installing pyenv

Let's start by installing pyenv. The installation process varies depending on your operating system.

On macOS

Using Homebrew:

brew update
brew install pyenv

To avoid them accidentally linking against a Pyenv-provided Python, add the following line into your interactive shell's configuration:

• Bash/Zsh:

alias brew='env PATH="${PATH//$(pyenv root)\/shims:/}" brew'

• Fish:

alias brew="env PATH=(string replace (pyenv root)/shims '' \"\$PATH\") brew"

On Linux

• Using curl:

curl https://pyenv.run | bash

After installation, add the following to your shell configuration file (e.g., .bashrc, .zshrc):

export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

• Using Package Manager On Arch Linux it can be installed with the help of pacman

sudo pacman -S pyenv

add the commands to ~/.bashrc by running the following in your terminal:

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

For Zsh:

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

For Fish:
If you have Fish 3.2.0 or newer, execute this interactively:

set -Ux PYENV_ROOT $HOME/.pyenv
fish_add_path $PYENV_ROOT/bin

Otherwise, execute the snippet below:

set -Ux PYENV_ROOT $HOME/.pyenv
set -U fish_user_paths $PYENV_ROOT/bin $fish_user_paths

Now, add this to ~/.config/fish/config.fish:

pyenv init - | source

For more detail, check out their GitHub.

Using Pyenv

1) Checking the Python Version

To check the Python version currently in use:

❯ pyenv versions
* system (set by /home/shanu/.pyenv/version)

2) Installing Python Versions

With pyenv, you can install any version of Python easily:

❯ pyenv install 3.11.9

After installing a python version, it can be set globally or locally for a project

3) Setting the Global Python Version

Not Recommended, may cause problems with your system
You can set a global Python version that will be used by default across your system:

pyenv global 3.10.6 

4) Setting the Local Python Version

You can also set a local Python version for a specific project directory. This version will override the global version when you are in that directory:

❯ pyenv local 3.8.10

❯ pyenv versions
  system
* 3.11.9 (set by /home/shanu/test_folder/.python-version)

❯ python -V
Python 3.11.9 (my global version is 3.12.5)

To unset it, just run:

❯ pyenv local --unset

❯ pyenv versions
* system (set by /home/shanu/.pyenv/version)
  3.11.9

❯ python -V
Python 3.12.5

5) Uninstalling Python Versions

To uninstall a Python version that is no longer needed:

pyenv uninstall 3.11.9

Conclusion

Pyenv is an invaluable tool for Python developers, especially when used in conjunction with Poetry. By managing Python versions effortlessly, it allows you to focus on writing code rather than worrying about version conflicts. Give it a try in your next Python project!