Virtual Environments I: Installing Pyenv with Homebrew

If you’ve used Python before, you may have encountered a situation known as “dependency hell”. Some packages depend on other packages to work. Sometimes, the package that another package depends on must be a certain version. Later on, you might need to use a different version of that package because there is yet another package that depends on that package being another version. So the best way to avoid dependency hell and create professional projects is to use virtual environments.

a lego toy office worker frustrated in front of a tiny computer
Image by www_slon_pics from Pixabay

This blog is part of a series of tutorials called Data in Day. Follow these tutorials to create your first end-to-end data science project in just one day. This is a fun easy project that will teach you the basics of setting up your computer for a data science project and introduce you to some of the most popular tools available. It is a great way to get acquainted with the data science workflow.

A virtual environment is like a little capsule for your project that contains all of the proper packages, in the proper version, in one spot. This makes it so you can switch from one project to another with ease. It also makes it so others can reproduce it later on. In this tutorial I’m going to go over how you can install packages to manage your virtual environments on MacOS.

I. Installing Pyenv with Homebrew

There are different virtual environment packages, but I like to use Pyenv. These instructions will be for MacOS/Linux but if you have Windows you can learn more about that here.

  1. First, open the terminal and and make sure you are using Bash. You will know you are using bash if you see this on the first line:

Alternatively, you might see your username followed by the dollar sign:


Keep in mind that the commands I am providing are in bash, so if your default language in the terminal is different (for example, Zsh), just enter:


This will allow you to enter commands in Bash. If you’re interested in what is going on with MacOS, Bash, Zsh, and why they’re changing that up, you can read about that here.

2. To check to see if you already have Homebrew, enter:

$ brew update

If it is indicated that you do not have Homebrew, I recommend reading this tutorial to ensure that you are properly set up to complete these instructions.

3. Now, we can install Pyenv with Homebrew.

$ brew install pyenv

I know this seemed a little too easy, so here is the catch. There is a special file that you need to access to make this actually work. As a beginner, I always found this part to be tricky, so I’ve broken it down into little pieces. This explanation might be a little granular for a more advanced user, but I tried to be a specific as possible for the sake of the beginner.

II. Using Bash and Nano to Create a .bash_profile

4. The file you need to access is known as .bash_profile. Notice the . at the front. When you see a dot in front of a file name, that means that the file is a hidden file.

5. When we start the terminal, we are starting in our home directory. Your home directory is generally named your username. To see the files in your home directory, you can type the bash command ls. However, if you want to see hidden files you need to add the the argument -a.

6. Enter the following:

$ ls -a

A list of all the files, including the hidden files, will appear.

Just as an aside — when you’re entering the commands you do not need to enter the dollar sign. It is already there for you. The reason that I’m using it in the commands is to indicate that the commands are in Bash.

7. Look carefully at the files. Do you see a file called .bash_profile? If you do skip to step ten. If not, we will make it together.

8. The terminal in a Mac will come preloaded with a light text editor that you can access in the terminal called nano. To open nano, simply enter:

$ nano

You can use any other text editor to do this if you want as well.

screen shot of a nano file
screen shot of a nano file
screen shot of a nano file

9. To create the file we need, don’t add any text just yet. Simply hit CTRL+x, which is the command to exit nano. On the bottom of the screen you will see a prompt that asks you if you want to save the file. Enter Y. Now, you will be prompted to enter a name for your file: .bash_profile. Hit enter and your file will be saved, and you will be returned to the terminal.

10. Now that you have that all set up, it’s time to add Pyenv to your $PATH. All this means is that it will enable you to use Pyenv in the command line — which is what we need. To do this, copy these lines into your terminal:

echo ‘export PYENV_ROOT=”$HOME/.pyenv”’ >> ~/.bash_profile
echo ‘export PATH=”$PYENV_ROOT/bin:$PATH”’ >> ~/.bash_profile

11. Now, we are going to open .bash_profile by typing `nano open .bash_profile` into the terminal. Then, paste the following line inside:

eval “$(pyenv init -)”

Enter X and those changes should save automatically.

12. For some of us, the code that we pasted into .bash_profile will also need to be pasted into .bashrc. To do this, follow steps 2–6 , except use .bashrc when nano prompts you to name the file. Then, skip item 7. Finally, repeat item 8, replacing .bash_profile with .bashrc .

13. Exit the terminal by entering:

 exec $SHELL

This will reset the terminal and apply the changes we just made. Keep in mind, this might switch the mini-language in your terminal back to Zsh. If that is the case, you will want to switch back to Bash.

III. Using Pip to Install Virtualenv

The next step is installing Virtualenv to use with Pyenv to manage our virtual environments and subsequent dependencies.

14. Use the following commands to call on Pip to install Virtualenv.

$ pip3 install virtualenv
$ pip3 install virtualenvwrapper

15. Now that we have Virtualenv, we need to install pyenv-virtualenv. Yes, we need both.

$ brew install pyenv-virtualenv

Open .bash_profile and/or .bashrc in nano, and add this line to the end:

eval “$(pyenv virtualenv-init -)”

IV. What Did We Do?

1. Updated Homebrew and installed Pyenv
2. Displayed secret files in our home folder.
3. Located and/or created a .bash_profile and .bashrc file using nano.
4. Added Pyenv to our $PATH so we can use it in the command line.
5. Installed virtualenv, virtualenvwrapper, and pyenv-virtualenv.
6. Properly configured pyenv and virtual env to our shell by adding code to .bash_profile and .bashrc.

V. What’s Next?

In the Virtual Environments II, I’ll show you how to create a unique virtual environment for your project and install some of the most popular data science packages, like Jupyter Notebook and Pandas.

If you liked this tutorial, check out more tutorials as Data in Day.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store