Why did pip install a package into ~/.local/bin?

Question

When I install this "Taurus Blazemeter 'bzt'" program with pip, it ends up being installed into ~/.local/bin folder.

mkdir ~/bzt && cd ~/bzt
sudo apt-get install python default-jre-headless python-tk python-pip python-dev libxml2-dev libxslt-dev zlib1g-dev
sudo pip install bzt

Does anyone know what use this ~/.local folder is for and why a Python program like this one would install there?

Answer 1

The short answer is that ~/.local/bin is the default value of Python's User Script Directory and that pip may install executables into this directory if it performs a user-local installation. It may also install files into other subdirectories of ~/.local, which is the default value of the User Base Directory. More details below.

---

I'm not sure if this is its earliest introduction, but the ~/.local directory appears in the file-system hierarchy specification of the systemd init system, where it defines several subdirectories of ~/.local:

~/.local/bin

Executables that shall appear in the user's $PATH search path. It is recommended not to place executables in this directory that are not useful for invocation from a shell; these should be placed in a subdirectory of ~/.local/lib instead. Care should be taken when placing architecture-dependent binaries in this place, which might be problematic if the home directory is shared between multiple hosts with different architectures.

~/.local/lib

Static, private vendor data that is compatible with all architectures.

~/.local/lib/arch-id

Location for placing public dynamic libraries. The architecture identifier to use is defined on Multiarch Architecture Specifiers (Tuples) list.

~/.local/share

Resources shared between multiple packages, such as fonts or artwork. Usually, the precise location and format of files stored below this directory is subject to specifications that ensure interoperability. If an application finds $XDG_DATA_HOME set, it should use the directory specified in it instead of this directory.

The adoption of the ~/.local directory by Python appears to have been introduced in Python 2.6 and is documented in PEP (Python Enhancement Proposal) 370:

• PEP 370 -- Per user site-packages directory

The specification includes the following definitions for Unix systems (including Mac OS X).

• User Base Directory

  ~/.local

• User Script Directory:

  ~/.local/bin

• User Site Directory:

  ~/.local/lib/python2.6/site-packages

• User Data Directory:

  ~/.local/lib/python2.6

From this we can conclude that Python has the concept of a so-called "Base User Directory" and that its default value is ~/.local. The Base User Directory is discussed in the Python documentation for the site module. In particular, it provides methods for determining the values of your User Base Directory and User Site Directory, the --user-base and --user-site options flags. You could use them like so:

user@host:~$ python -m site --user-base

/home/user/.local

user@host:~$ python -m site --user-site

/home/user/.local/lib/python2.7/site-packages

There are several questions posted to StackExchange sites related to the ~/.local directory which I used as references:

• Why should I install Python packages into ~/.local?

• Whats the .local folder for in my Home Directory

• Why is ~/.local/share a two-level directory?

• Which distributions have $HOME/.local/bin in $PATH?

• Understanding home configuration file locations: ~/, ~/.config/ and ~/.local/share/

• user site-package directory

• What is the simplest way to do a user-local install of a python package?