How do I install a Python command line tool or script? (hint: pipx)
Tags: python, pipx, commandline
Published: 2020-08-20 10:31:34

* [Installation](#installation)
  * [Generic installation](#installation-generic)
  * [On Mac](#installation-mac)
  * [On Windows](#installation-windows)
  * [On Linux](#installation-linux)
  * [Troubleshooting PATH environment variable](#installation-path)
* [Using `pipx`](#usage)

***

With [pipx], you can install a Python-based command line tool in a manner that is safe, stable, and convenient. It is like Node/npm's [npx], but for Python. In other words, it is a package runner. It installs the requested package, but in an isolated environment with the correct dependencies, so you can run the associated script(s) as command line tools.

> `pipx` does not replace `pip` or virtual environments. For normal Python development, use [virtual environments and `pip`](https://dev.to/bowmanjd/python-dev-environment-part-1-setup-py-venv-and-pip-22gd) or [use a tool like Poetry](https://dev.to/bowmanjd/getting-started-with-python-poetry-3ica). What `pipx` provides is isolation and convenience. In fact, `pipx` uses virtual environments and `pip` to accomplish these goals.

`pipx` allows you to install useful command line tools like `virtualenv`:

```
$ pipx install virtualenv
  installed package virtualenv...
done!
$ virtualenv
usage: virtualenv...
```

In other words, `pipx` can be used to install any Python package with executables that you want to access from the command line, system-wide. <a name="installation"></a>

## Installation

I have included step-by-step instructions in this article, but the official installation instructions are [here](https://github.com/pipxproject/pipx#install-pipx). <a name="installation-generic"></a>

### Generic instructions

If you understand your platform, and already have Python 3 installed, this should install pipx:

```
python3 -m pip install --user pipx
python3 -m pipx ensurepath
```

Use `python`, `python3`, `python3.9`, `py -3` or whatever gets you a decent Python 3 interpreter.

Running `pipx ensurepath` includes `pipx` in your PATH variable. In other words, this makes sure that entering `pipx` by itself will find the right executable.

The above may work for you. However, the platform-specific instructions may suit your circumstances better. <a name="installation-mac"></a>

### Installation on a Mac

Do you have [Homebrew](https://brew.sh/)? If not, install it with this:

```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
```

Because using a Mac without Homebrew is like

![Sad Mac](https://dev-to-uploads.s3.amazonaws.com/i/qxkjroevz2fpw6zl8yig.jpg)

See [the Homebrew homepage](https://brew.sh/) for more detail.

Then install `pipx`:

```
brew install pipx
```

Then run `pipx ensurepath`. <a name="installation-windows"></a>

### Installation on Windows

First, install Python. Various ways to do that. If unsure, go to [python.org](https://www.python.org/downloads/) and download and run the installer.

Once installed, launch Powershell and then follow the [generic directions above](#installation-generic).

I did have a bit of trouble with PATH and Windows. I think this was resolved when I closed my Windows Terminal (all tabs) and restarted it... Who am I kidding. I just rebooted Windows, because that is what you do.

I made sure that these two were in my PATH environment variable:
* Because I installed pipx using `pip install --user`, the `pipx` executable was in `C:\Users\my_username\AppData\Roaming\Python\Python38\Scripts`
* `pipx`-installed executables are in `C:\Users\my_username\.local\bin`

Searching the Start Menu for "Environment" will get you to a place where you can check and edit the user's PATH variable.
<a name="installation-linux"></a>

### Installation on Linux

Your package manager (such as `apt` or `dnf`) may have `pipx` in the repositories somewhere, so that `apt install pipx` or `dnf install pipx` should work.

Otherwise, make sure you have Python 3 installed, then, if your distro weirdly separates out `pip` and `venv`, make sure you install packages like `python3-pip` and/or `python3-venv`.

Then follow the [generic directions above](#installation-generic).

If `python -m pip` shows an error like "The virtual environment was not created successfully because ensurepip is not available," follow the instructions given or install pip and venv [following the official guide](https://pip.pypa.io/en/stable/installing/). <a name="installation-path"></a>

### Doctoring PATH

Because systems are all different, and often customized, there is a slim chance that `pipx ensurepip` doesn't change the PATH environment variable permanently. Or you might simply be someone who wants to handle this setting yourself, rather than running `pipx ensurepip`.

Setting the PATH variable on Windows is [explained above](#installation-windows).

On Linux, Mac, and other Unix-like systems, check the PATH variable with:

```
echo $PATH
```

You should see a colon-separated list of filesystem paths, in which various executables reside. If `/home/your_username/.local/bin` is in that list, you are golden.

If you need to edit the PATH variable, there will be a file or files in your home directory in which to set it. I would suggest checking the files in this order:

1. `~/.bashrc`
1. `~/.bash_profile`
1. `~/.profile`
1. `~/.zshrc`

You can edit any of these with the text editor of your choice. If you are not sure what to use, try `nano` from the command line. If you know Vim, try `vim` or `vi` but beware that twenty years from now you may still be using Vim because you don't know how to quit.

The line you want to add or edit is:

```bash
export PATH=$PATH:$HOME/.local/bin
```

If you use `zsh`, you could get away with

```zsh
path+=$HOME/.local/bin
```

Once you logout and log back in, or in some cases just restart your terminal, you should have pipx and any installed commands available from your command prompt.  <a name="usage"></a>

## `pipx` usage

Here are some `pipx` commands I find useful:

* `pipx install youtube-dl` - installs a new package, in this example, "youtube-dl" (hmmm... I wonder what that package does)
* `pipx upgrade virtualenv` - this upgrades a specific package. In this example, the package "virtualenv" is upgraded
* `pipx upgrade-all` - upgrades _all_ packages installed with `pipx`
* `pipx list` - shows all the packages installed and path information
* `pipx run youtube-dl` - temporarily downloads, installs, and runs the package "youtube-dl" without affecting your environment

I hope you find these examples useful!

[pipx]: https://pypi.org/project/pipx/
[npx]: https://www.npmjs.com/package/npx