DO NOT PIP INSTALL, PLEASE!

Disclaimer: This article is for the hobbyists and people who are not coding on a daily basis.

Believe it or not, thousands of Python developers still pip install directly into their global environment—living dangerously and battling conflicts like it’s the Wild West of coding. ????:

• Package Conflicts: Direct installation modifies the global Python environment. If you later work on another project requiring different versions of the same package, one day you will wake up to a conflict for sure. In addition to that, upgrading or downgrading a package for one project might break functionality in another.
• Difficulty in Reproducing Environments: without a virtual environment, there's no isolated record of the packages and versions used for yo?r project. So it may work for you, but it won't most probably if you want to use it somewhere.
• Cluttered Global Environment: Your global environment will bloat with packages you don't need anymore.
• Risk of Breaking System Tools: Some operating systems rely on Python and specific packages for system tools. You will most probably break it with directly pip install.
• Security Risks: If a package with vulnerabilities is installed globally, it might pose a greater security risk since it affects the entire system rather than a specific project.
• No Easy Environment Cleanup: Virtual environments can be easily deleted and recreated without affecting the global Python installation. If you install packages globally, cleaning up becomes more labor-intensive.

What should we do? Simple: Virtual environments, dependency managers and environment managers

I know it sounds too much, but once you are done, you will see how easy it is.

Environment Manager: Pyenv

Pyenv (https://github.com/pyenv/pyenv) is an environment manager that lets you use different python versions with ease. This might be an optional step for you, if you are not planning to use one/base version you have. However, newer python versions generally have really useful versions, therefore, I'd highly recommend to utilize that features.

It is quite easy to install:

MacOs:

brew install pyenv        

Linux:

git clone https://github.com/pyenv/pyenv.git ~/.pyenv        

Afterwards add the pyenv root to the path. Following code will do the trick the for zsh terminal, replace the .zshrc with .bash_profile to install it for bash:

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

Don't forget to reload your shell with source ~/.zshrc .

Windows (Powershell):

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"        

Now lets install our first Python instance

pyenv install <version> will simply install which version you want to have. To see versions you've installed, you can run pyenv versions:

Now we are ready to set up the virtual environment for our projects. I will show how to select the python version while setting up the package manager.

Package Manager: Poetry

Imagine you’re a poet, but instead of crafting beautiful stanzas with words, you're managing dependencies and packages in your Python projects. That’s where Poetry (https://python-poetry.org/) comes in—no rhymes required! ???

Poetry is a powerful tool designed to make working with Python projects easier and more organized. We will use it to handle everything from installing libraries to managing different versions of dependencies (so you don’t accidentally break your project when something updates).

To install:

For macOS Users

Run the installation command on your terminal:

curl -sSL https://install.python-poetry.org | python3 -        

Update Your Path: Add Poetry to your shell configuration (like .zshrc or .bash_profile):

export PATH="$HOME/.local/bin:$PATH"        

and that is it! You can also of course use brew install poetry ??

For Windows Users

• Open PowerShell: The magic happens here! Right-click and “Run as Administrator” to avoid permission hiccups.
• Run the Installation Command:

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -        

• Check Your Path: Make sure C:\Users\<YourUsername>\AppData\Roaming\Python\Scripts is in your system’s PATH.
• Press Win + S, search for "Environment Variables," and click "Edit the system environment variables.
• "In "System Properties," go to the Advanced tab → Environment Variables → Edit Path.

For Linux Users ??

• Open Terminal: Linux wizards, you know the drill.
• Run the Installation Command:

curl -sSL https://install.python-poetry.org | python3 -        

• Update Your Path: Add Poetry to your shell configuration (like .bashrc or .zshrc):

export PATH="$HOME/.local/bin:$PATH"        

• Reload your terminal:

source ~/.zshrc        

Let's get finally started

Now after all the fuzz, we are going to have a clean and organized project setup that works like a charm.

Setting Up Your Project with Poetry

• *Optional: Set your python version: Navigate to your project folder, and set your version with pyenv local <version>.

• Initiate poetry: use poetry init command in your folder and follow the instructions

You can of course add your dependencies on this step, however, it is not mandatory. This will create the pyproject.toml file. Also, note that, I defined my python version preference when it is asked.

• Create the virtual environment: If you skipped the first step and pyenv, you can simply type poetry install --no-root and hit enter. This will create the virtual environment - a copy of your python, isolated for this project. If you followed my path and used pyenv, here is the command you need to run:

poetry env use $(pyenv which python)        

Poetry always wants to create the virtual environment with the global python instance, that is why it suggested the 3.11 during the initialization. This command tells poetry to use the python version you set up with the pyenv.

Of course, for windows, you should replace $(pyenv which python) with the path of the python executable, as the $ syntax does not work with cmd. Simply, run pyenv which python, and copy the output after poetry env use.

If you've defined dependecies during the initialization, you should run poetry install --no-root to install them.

• Add Dependencies: To add a package as a dependency, run:

poetry add <package_name>        

• Activate the Virtual Environment: Poetry automatically manages a virtual environment for your project. To activate it:

poetry shell        

• Run Your Project: Inside the virtual environment, run your scripts as usual:

python main.py        

• Lock Dependencies: When you've finalized your dependencies, Poetry generates a poetry.lock file to ensure your project runs with the same package versions everywhere. Commit this file to your version control system.

A Glimpse of the Magic ?

Here’s what your development life might look like after adopting this workflow:

• Switching Projects: You no longer worry about breaking projects or installing unnecessary global packages.
• Collaboration: Team members can recreate your environment effortlessly, avoiding the dreaded "It works on my machine!" moments.
• Portability: Moving between machines or sharing your work becomes seamless.
• System Integrity: Your global Python remains untouched, ensuring your OS tools continue to function.

TL;DR: Adopt Virtual Environments, Stay Sane ??♂?

To summarize:

• Use Pyenv to manage Python versions.
• Use Poetry to manage dependencies and isolate environments.
• Focus on coding, not fixing broken setups.

This approach is beginner-friendly, scalable, and most importantly, makes coding a joy rather than a hassle. Trust me, once you embrace this workflow, there’s no turning back.

BONUS CHAPTER: UV Package Manager

Meet uv (https://github.com/astral-sh/uv), the new player in the Python package management game, built by the brilliant minds behind tools like Ruff. If you’re looking for an all-in-one solution for managing Python versions, dependencies, and even project tools, uv might just steal your heart.

Think of uv as the Swiss Army knife for Python projects. It combines the functionality of tools like pyenv, poetry, pip-tools, and even virtualenv—all in one neat package. And it is fast, I mean, fast. It has the popular rust magic in it!

Have you tried uv yet? Drop your thoughts in the comments below! Let’s discuss how this new kid on the block is shaping Python development. ????

If you found this helpful, feel free to like, comment, or share your experiences with virtual environments. Let's help more hobbyists and occasional coders build better Python projects!

Happy coding! ???