I've programmed in python on and off for fun the past few years. Learning the language itself wasn't difficult. What can be frustrating when learning a new language is the tooling. New languages can involve a different IDE, new libraries, new package managers, etc. it's like entering a new world OR a new environment 😜.

When I started writing in python, I just wanted to get something running. It wasn't some huge or serious project, just something fun or quick. A concept I missed initially was virtual environments. Using them would have saved so much frustration. At times there'd be several weeks or months between working on a project. I'd come back update my packages or python itself and instead of trying out my new idea, I ended up creating a problem. The updates broke my app. Instead of moving forward with something, I'd end up fixing the app or my system environment 😦.

What are Virtual Environments

A virtual environment (venv for short) is a collection of package dependencies, binaries and python interpreters which are isolated from the operating system's python installation and other projects.

The virtual environment directory mimics the python base installation and typically created in the project root directory. The folder will either point to the system's python interpreter or links to it. It also contains packages that you install while it's activated.

Before writing the first line of code for a project, start by setting up the venv. It'll save you a ton of trouble and will help isolate and manage project dependencies.

For a deeper dive on how it works check out the official docs.

Setting up an venv

Here's basic folder structure for a project. The .venv directory gets created goes in the root of the project. It should not be checked into the your source control system. It'll need to be created when the repository is cloned. Here's how to setup your project's virtual environment for the first time.

Your project directory might look something like this

project-root \ 
| src \ 

First navigate to your root project

$ cd project-root

Once in your root all you need to do to initialize the environment is:

$ python -m venv ./venv

The argument to venv command is the path of the venv directory. Conventially its named 'venv' or '.venv'. After executing it, your project directory will look like this:

project-root \ 
| src \ 
| venv \

To activate the environment (from the root of the project):

$ ./venv/Scripts/activate

At this point packages can be installed without causing conflicts with other projects. As you install dependencies you can extract them and save to a file by running pip freeze:

pip freeze > requirements.txt

Add the requirements.txt file to your code repository. The packages in the virtual environment can simply be installed by running pip install -r requirements .

Reference

Official Python Docs - venv