How do I install a Python command line tool or script? (hint: pipx)

• Installation
  • Generic installation
  • On Mac
  • On Windows
  • On Linux
  • Troubleshooting PATH environment variable
• Using pipx

---

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 or use a tool like Poetry. 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.

Installation

I have included step-by-step instructions in this article, but the official installation instructions are here.

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.

Installation on a Mac

Do you have Homebrew? 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

See the Homebrew homepage for more detail.

Then install pipx:

brew install pipx

Then run pipx ensurepath.

Installation on Windows

First, install Python. Various ways to do that. If unsure, go to python.org and download and run the installer.

Once installed, launch Powershell and then follow the generic directions above.

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.

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.

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.

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.

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
2. ~/.bash_profile
3. ~/.profile
4. ~/.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:

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

If you use zsh, you could get away with

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.

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!

Comments

[Rick Valenzuela]

Thanks for this article! Question, tho: Would you do this when managing python version installs with asdf? Currently, I'm using asdf and setting global to latest.

[Tolga Karahan]

So it install each package and its dependencies into a different isolated environment, but still we are able to use this packages in system wide?

[Jonathan Bowman]

Yes, you have it right! It places links to executables in your PATH.

[Tolga Karahan]

Thanks.