Python pip: A Complete Guide

You have probably seen the pip command somewhere in the Python documentation. If you have ever stumbled across any third-party library in Python, you know that the first line mentions the pip command. This one command plays a key role in your project: pip lets you download and manage packages.

If you have ever used package managers in other languages, like npm in JavaScript or gem in Ruby, you are already familiar with the concept of package management. The sole purpose of pip is to help you manage packages in your Python project.

This tutorial will discuss how to use the Python pip tool to add and remove packages from your Python project. We’ll walk you through some examples as well to help you get started with this tool.

What is pip?

pip is a package management system written in Python. It is a tool that helps to install and manage third-party libraries and packages. The pip tool is extremely crucial to Python development, and it is included with the Python environment installation since Python 2.7.9. 

Let’s say you created a fresh project using Python for a machine learning task. While you may have the dataset and the applicable algorithm for the task at hand, it is not advisable to write the code for the algorithm from scratch. Popular open-source libraries like Keras and Tensorflow already contain pre-written, optimized code for your algorithms. Libraries like Pandas and NumPy contain a routine of methods to help you pre-process or clean your dataset easily. You want to be able to use these directly in your project.

That’s where the Python pip tool comes in. The pip tool allows you to install these packages directly from the Python Package Index in a hassle-free process.

Python Packages: A Refresher

In a computer, files are not usually all stored in the same location. Every user follows a different structure for organizing files and folders for easy access. Similar files are usually grouped together, under a common directory, as they have a similar purpose. Instead of directories, however, libraries and methods are organized using what we call modules and packages. This is another method of file organization.

A Python module is a collection of methods and properties which share a common purpose. A package further groups similar modules together to present an independent ecosystem of code that can help solve a bigger problem. More often than not, projects require traditional algorithms to be followed to complete routine tasks like data sorting, searching, or data manipulation. Writing code for these use-cases inside your project can increase clutter, as the focus can shift from your business logic to your sorting and searching methods.

To solve this issue, code for such routine tasks is usually written in separate modules, which helps to reduce the clutter in the main project, as well as allows for better testing and individual development on this code. These packages can then be exported and made available to a big number of developers with package distribution systems like the Python Package Index. Then, you can install a package using pip.

Python pip Tool

Installing Packages

The pip tool can be used to install packages available over the Python Package Index via the command line. pip comes preinstalled with most modern versions of Python. You need to put the name of the package that you wish to install in your project in the following syntax:

pip install package_name

As you can see, the above command is composed of three parts: 

• pip: Instructs the terminal to invoke the pip tool and pass the trailing tokens as arguments to it.
• install: Instructs the pip tool that a package needs to be installed.
• package_name: Denotes the name of the package that has to be installed.

Here’s how you can use this syntax to install the popular statistical library Numpy:

pip install numpy

If you have worked with npm, used for JavaScript development, the syntax is nearly the same:

npm install package_name

The tool looks for the package by name in the PyPI (Python Package Index) and installs the package if it is available. 

You can also install multiple packages at once, using the following syntax:

pip install package1 package2 package3 ...

This is how you would use this syntax in a real-life scenario:

pip install numpy pandas

Using the requirements.txt File

The above method can get quite cumbersome if you have a long list of packages to install. pip offers a way of installing packages using a requirements.txt file. This is how a usual requirements.txt file looks:

###### Packages that are not version-specific
numpy
pandas
beautiful-soup

###### Packages that require certain versions to be installed
docopt == 0.6.1.            # When looking for the exact version
keyring >= 4.1.1.           # When looking for any version above the               
                              specified one
Mopidy-Dirble ~= 1.1.       # When looking for a compatible release. 
                              Equivalent to >= 1.1or == 1.*

And this is how the syntax of a pip call with a requirements.txt file looks like:

pip install -r requirements.txt

Uninstalling Packages

Many times, it is necessary to remove packages from your projects for maintenance or upgrading purposes. The pip tool can be used to remove packages from your project as well:

pip uninstall package_name

As you can see, the above command is composed of three tokens: 

• pip: Instructs the terminal to invoke the pip tool and pass the trailing tokens as arguments to it.
• uninstall: Instructs the pip tool that an installed package needs to be removed.
• package_name: Denotes the name of the package that has to be removed.

You can use the above syntax to uninstall any library, such as NumPy, like this:

pip uninstall numpy

Once again, this syntax is similar to that of npm’s JavaScript package library:

npm uninstall package_name

For uninstalling multiple packages, you can follow this syntax:

pip uninstall package1 package2 package3 ...

This is how it would be used in a real-life scenario:

pip uninstall numpy pandas

You can also use the requirements.txt file to uninstall a list of packages at once:

pip uninstall -r requirements.txt

Viewing All Installed Packages

Very often, you will need to view the list of packages that are installed in your project locally. Doing so helps you to identify if a package has been installed before, and helps you check if a certain version of a package is present in your project. The pip list command shows a list of all packages in your project. Here’s how you can use the command:

pip list

This will return an output similar to this:

"Career Karma entered my life when I needed it most and quickly helped me match with a bootcamp. Two months after graduating, I found my dream job that aligned with my values and goals in life!"

Venus, Software Engineer at Rockbot

Find Your Bootcamp Match

docutils (0.10)
Jinja2 (2.7.2)
# ...and so on

Alternatively, you can pass an outdated option to retrieve a list of all packages with their current and latest available versions. This helps to identify which packages need to be updated. This is how the syntax looks like:

pip list --outdated

This is how a usual output would look like:

docutils (Current 0.10 Latest: 0.11)
Sphinx (Current: 1.2.1 Latest 1.2.2)

Viewing Details for an Installed Package

The pip show command helps you to view the details of an installed package in your Python project. It returns details like version, author, license, and dependencies for the said package. Its syntax is simple:

pip show sphinx

This is how a sample output would look like:

Name: Sphinx
Version: 1.4.5
Summary: Python documentation generator
Home-page: http://sphinx-doc.org/
Author: Georg Brandl
Author-email: georg@python.org
License: BSD
Location: /my/env/lib/python2.7/site-packages
Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six

Freezing Package Versions

An important feature that all package managers need to have is the ability to freeze packages to their set versions. This is important when the project is being developed on multiple systems, and the same version of packages is required across all of them to maintain the stability of the project. 

While you can list out the installed packages with their versions with the list command, you will need to manually format them according to the requirements.txt file format that we saw earlier if you want to install these dependencies quickly on another system.

The pip freeze command does this for you without any hassle. It prints the list of installed packages in the requirements format, and you can combine it with the output redirection operator of the command line to save it to a file. This is how the complete syntax would look like:

pip freeze > filename

You can directly create a ready-to-go requirements.txt file by using this command:

pip freeze > requirements.txt

Now you can put this requirements.txt file in the project in which you want to install these packages. We have already seen an example above on how to use such a file to install packages at once.

pip vs pip3

Since version 2.7.9 in Python 2 and version 3.4 for Python 3, the standard Python installation ships with a pip installation as well. But as Python moved from version 2 to 3, pip also was also upgraded to pip3. The introduction of Python 3 converted the old pip to a soft link to the new pip3. This means that when you are running the old pip on your command line with the new Python3 installed on your system, you are actually calling pip3. 

However, if you have both Python 2 and Python 3 installed on your system, then the pip command runs the pip installer associated with your Python 2 installation, and the pip3 command runs the pip3 installer associated with your Python 3 installation. The syntax for both pip and pip3 are the same, you just need to replace pip with pip3. Here’s how you can install NumPy using pip3:

pip3 install numpy

All other commands work similarly.

Conclusion

The Python pip tool contains a list of commands to help you manage your packages efficiently. install and uninstall commands can be used to add or remove packages easily. list and freeze can be used to view the list of installed packages in raw/formatted manner. show can be used to view all details of one package at once.

This tutorial discussed, with reference to syntax and examples, the basics of PyPI packages, and how to use them with the pip tool. Now you are ready to start using the official Python package manager like a Python pro!