Python Typer Packaging and Distribution Guide

Packaging Typer CLI apps makes them easy to install and run. This guide covers setup with console_scripts entry points.

Why Package Typer Apps?

Packaging lets users install your CLI tool system-wide. It creates executable commands without typing python script.py.

Entry points register commands during installation. Users can run them directly from any terminal.

Basic Package Structure

Here's a minimal project structure:

my_cli_app/
├── my_cli_app/
│   ├── __init__.py
│   └── cli.py
├── pyproject.toml
└── README.md

Creating the Typer App

First, create a basic Typer app in cli.py:

import typer

app = typer.Typer()

@app.command()
def greet(name: str):
    """Greet someone by name"""
    typer.echo(f"Hello {name}!")

if __name__ == "__main__":
    app()

Configuring pyproject.toml

Modern Python packaging uses pyproject.toml. Add this configuration:

[build-system]
requires = ["setuptools>=42"]
build-backend = "setuptools.build_meta"

[project]
name = "my-cli-app"
version = "0.1.0"
description = "My awesome CLI tool"

[project.scripts]
mygreet = "my_cli_app.cli:app"

The project.scripts section defines the entry point. mygreet becomes the command name.

Installing in Development Mode

Test your package locally with:

pip install -e .

Now you can run mygreet directly:

mygreet John
# Output: Hello John!

Building and Distributing

Create a distributable package with:

python -m build

This generates files in the dist/ directory. Upload them to PyPI with twine.

Advanced Entry Point Configuration

For multiple commands, use separate functions. Update cli.py:

def main():
    app()

@app.command()
def greet(name: str):
    typer.echo(f"Hello {name}!")

@app.command()
def farewell(name: str):
    typer.echo(f"Goodbye {name}!")

Then update pyproject.toml:

[project.scripts]
mygreet = "my_cli_app.cli:greet"
mybye = "my_cli_app.cli:farewell"

This creates two separate commands. For more complex setups, see our Python Typer Boolean Flags guide.

Testing Your Package

Always test installed behavior. Verify commands work after installation. Our Typer CLI Testing guide covers this in detail.

Version Compatibility

Specify Python and Typer version requirements:

[project]
requires-python = ">=3.7"
dependencies = [
    "typer>=0.4.0",
]

Adding Metadata

Enhance your package with metadata. Include author info and classifiers. For advanced options, see our Typer Metadata guide.

Conclusion

Packaging Typer apps with console_scripts makes them user-friendly. Follow these steps for professional CLI tools.

Remember to test thoroughly before distribution. Proper packaging ensures smooth installation and usage.