how-to-pipx.md

Using pipx

pipx is a tool for installing and running Python applications in isolated environments. It's especially useful for Python-based tools and scripts that are intended to be run from the command line, rather than imported into other Python code. By using pipx, you can install applications and their dependencies in isolated environments, avoiding conflicts between packages and ensuring that each application has the specific versions of libraries it requires.

Installation

macOS

Install using brew install pipx or manually, using: python -m pip install --user pipx.

Afterwards, run pipx ensurepath to ensure that pipx in is your PATH.

Using pipx to install Python packages

Once pipx is installed, you can use it to install Python applications. For example, if you want to install a package like black (a popular Python code formatter), you can do so like this: pipx install black

This command installs black in an isolated environment. It includes all necessary dependencies, but these dependencies won’t interfere with any other Python environments or dependencies on your system.

Running Installed Applications

After installing an application with pipx, you can run it directly from the command line, just like any other command-line tool: black my_script.py

This command would format the Python script my_script.py using the black formatter.

Managing Installed Applications

pipx provides commands for managing the applications you've installed. Some of the most commonly used are:

• List installed applications: pipx list
• Upgrade an application: pipx upgrade black
• Uninstall an application: pipx uninstall black
• Uninstall all pipx-installed applications: pipx uninstall-all

Running Temporary Applications

pipx also allows you to run an application directly, without permanently installing it, using the run command. For example: pipx run pycowsay "Hello, World!"

This command runs the pycowsay application, temporarily installing it in an ephemeral environment just for that execution.

Using pipx with your own projects

Using pipx for your own Python projects, particularly those designed to be command-line applications or tools, involves a few specific steps to prepare and manage the distribution of your project. Here’s how you can set up and use pipx with your own Python projects:

Step 1: Prepare Your Project for Distribution

First, ensure your project is structured appropriately and includes a setup.py file or uses pyproject.toml if you're leveraging more modern tools like Poetry or Flit. Here’s an example structure:

my_project/
│
├── my_project/
│   ├── __init__.py
│   ├── cli.py     # Your command-line interface
│   └── core.py    # Core functionality
│
├── setup.py       # setup script for setuptools
└── pyproject.toml # Configuration for build system (if using modern packaging like Poetry)

For a simple setup.py that makes your application installable and executable:

from setuptools import setup, find_packages

setup(
    name='my_project',
    version='0.1.0',
    packages=find_packages(),
    entry_points={
        'console_scripts': [
            'my-command=my_project.cli:main',  # "my-command" is the command you'll use in the terminal
        ],
    },
    install_requires=[
        # List your project's dependencies here
        'requests',
    ],
)

If you are using pyproject.toml for a tool like Poetry, your file might look like this:

[tool.poetry]
name = "my_project"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.24.0"

[tool.poetry.scripts]
my-command = "my_project.cli:main"

Step 2: Build and Test Locally

Before distributing your project or using pipx, you should build and test it locally:

• If using setuptools, you can build your project with:

  python setup.py develop

  This command installs the project in development mode, allowing you to test it.

• If using Poetry:

  poetry install

  This will install your project along with its dependencies in a virtual environment managed by Poetry.

Step 3: Install with pipx

Once you're satisfied with your local testing, you can use pipx to install your project globally, directly from your project directory or from a Git repository, if it's hosted online.

• From local directory:

  pipx install .

  Run this command from within the directory containing setup.py or pyproject.toml.

• From a Git repository:

  pipx install git+https://github.com/yourusername/my_project.git

Step 4: Use Your Command-Line Tool

After installing with pipx, you can run your command-line tool from anywhere using the command specified in your entry_points or scripts:

my-command args

Updating Your Tool

If you make changes and want to update the tool installed via pipx:

pipx upgrade my_project

#python #pipx #poetry