Pip is the standard package management tool for Python. Iis normally installed together with the interpreter, but in some cases the user may be required to perform a separate manual installation. You can check whether pip is installed and accessible by simply typing pip in the command-line interface(cmd)/shell. 

The basic usage of pip involves passing the commands in the cmd/shell using the following format.

pip <command> [options]

In this article we will narrow our interest into pip's install command which is typically used for installing packages from any of the following sources:

  • PyPi (Python Package index) - An online repository for python packages.
  • Custom repository.
  • Local project directory.

Basic usage and syntax

Installing from PyPi is the most common way that packages are installed using pip. The basic syntax is as shown below: 

pip install <package> [options] <requirement specifier>

The <package> parameter represents the name of the package to be installed. For example to install the "flask" package we may run the install command as shown below:

pip install flask  #install the latest version
pip install flask==2.3.2  #install a specific version
pip install flask <= 2.3.1 #install a minimum version

As previously shown in the syntax, we can pass options in the install commands to further customize the installations. The options are usually predefined names that are preceded by a single or double hyphen. For example if we want to upgrade an already installed package, we can pass the --upgrade parameter as an option in the the installation command.

pip install flask --upgrade

If you run the above command, pip will check whether the currently installed version of flask is the latest one, if not, it will install the latest version and then uninstall the one that is currently installed.

You can pass many options at once, for example:

pip install flask --upgrade --user

The --user parameter in the options indicates that the package should be installed in the current user's directory rather than systemwide. 

There are many other install options, we will look at some of them later.

installing from a requirements file

A requirements file is simply a text file(conventionally named as "requirements.txt")  that lists all the packages that are required by a project. In its basic form the file may look as shown below.

flask
numpy
requests
matplotlib

In most cases, however,  we need to have the actual version for each package in order to avoid future conflicts in case new versions are uploaded to PyPi. So in most practical cases, the requirements.txt file looks as shown below:

flask==2.2.3
numpy==1.26.0
requests>=2.27.0
matplotlib==3.8.0

You do not have to write the requirements file manually if you already have an existing project. Pip's freeze command  can be used to auto-generate the file based on the packages that are installed in the active virtual environment. Its syntax is as follows:

pip freeze > requirements.txt

The above command will lead to creation of a file named "requirements.txt" containing the names and the versions for all of the currently installed packages.

When the requirements file already exists, we can automatically install the specified packages using the pip install command by specifying the -r parameter and the name of the file.

pip install -r requirements.txt

The above command is quite common, you may for instance be needed to run it when you work with projects written by other developers such as from github or other repositories.

Installing from a custom repository

The PyPi repository is located at https://pypi.org/simple , this is by default where pip looks for packages when you run the pip install command. Pip also allows you to specify a custom repository if necessary, this is achieved by using the -i parameter followed by the path/url to the repository and then the name of the package to be installed. The custom repository must conform to the simple repository API( as specified in PEP 503 )

The repository may be located at a local path or in a remote url.

pip install -i https://your-custom-repo/ <package name>

or

pip install -i /path/to/your/custom-repo <package name>

Installing from a local project directory

We also have the editable mode option which can be used to install a package from a local source. In this mode, Pip installs the package in the current working codebase rather than into some internal directories. This allows you to make direct changes to the project and perform tests without having to re-install the package.

To install a package in editable mode we use the -e or --editable option

pip install -e /path/to/project

This mode is especially useful if you are creating your own package or you want to modify or make improvements to an existing one.

Other install options

The following table summarizes some of the install options that we can use to further customize the installation process.

option description
-r, --requirements <file>

 

Install packages listed in the requirements file
-i, --index-url <url>

 

Install packages from a custom package index/repository.
-e, --editable <path/url>

 

Install a package from a local source in editable mode.
-t, --target <dir>

 

Install the package in the directory specified by <dir>.
-U, --upgrade

 

Upgrade the specified package(s) to their latest available version.
--no-dep

 

Don't install dependencies.
--pre

 

Include development and pre-release versions.
--dry-run

 

Print information about what packages would be installed without actually installing them (but downloading):

--user

 

Install the package in the current user's installation directory rather than in system-wide.
--force-install

 

Reinstall all packages even if they are already up-to-date.

There are still other available but least used install options, you can check them at the official documentation, here.