导航|地址|刷新
Creating and packaging command-line tool…
ContentsMenuExpandLight modeDark modeAuto light/dark, in light modeAuto light/dark, in dark mode
Hide navigation sidebar

Hide table of contents sidebar
Skip to content


Toggle site navigation sidebar



Python Packaging User Guide




Toggle Light / Dark / Auto color theme


Toggle table of contents sidebar



Python Packaging User Guide




Overview of Python Packaging

The Packaging Flow

Tutorials
Toggle navigation of Tutorials

Installing Packages

Managing Application Dependencies

Packaging Python Projects


Guides
Toggle navigation of Guides

Installation
Toggle navigation of Installation

Install packages in a virtual environment using pip and venv

Installing packages using virtualenv

Installing stand alone command line tools

Installing pip/setuptools/wheel with Linux Package Managers

Installing scientific packages


Building and Publishing
Toggle navigation of Building and Publishing

Writing your pyproject.toml

Packaging and distributing projects

Dropping support for older Python versions

Packaging binary extensions

Packaging namespace packages

Creating and packaging command-line tools

Creating and discovering plugins

Using TestPyPI

Making a PyPI-friendly README

Publishing package distribution releases using GitHub Actions CI/CD workflows

How to modernize a setup.py based project?

Licensing examples and user scenarios


Hosting
Toggle navigation of Hosting

Package index mirrors and caches

Hosting your own simple repository


Tool recommendations

Analyzing PyPI package downloads


Discussions
Toggle navigation of Discussions

Versioning

Deploying Python applications

pip vs easy_install

install_requires vs requirements files

Distribution package vs. import package

Package Formats

src layout vs flat layout

Is setup.py deprecated?

Single-sourcing the Project Version

Supporting downstream packaging


PyPA specifications
Toggle navigation of PyPA specifications

Package Distribution Metadata
Toggle navigation of Package Distribution Metadata

Names and normalization

Core metadata specifications

Version specifiers

Dependency specifiers

pyproject.toml specification

Dependency Groups

Inline script metadata

Platform compatibility tags

Well-known Project URLs in Metadata

glob patterns

License Expression


Package Installation Metadata
Toggle navigation of Package Installation Metadata

Recording installed projects

Entry points specification

Recording the Direct URL Origin of installed distributions

Direct URL Data Structure

Python Virtual Environments

Externally Managed Environments


Package Distribution File Formats
Toggle navigation of Package Distribution File Formats

Source distribution format

Binary distribution format


Package Index Interfaces
Toggle navigation of Package Index Interfaces

The .pypirc file

Simple repository API

File Yanking

Index hosted attestations

Project Status Markers


Python Description Formats
Toggle navigation of Python Description Formats

build-details.json
Toggle navigation of build-details.json

v1.0



Reproducible Environments
Toggle navigation of Reproducible Environments

pylock.toml Specification


PyPA schemas


Project Summaries

Glossary

How to Get Support

Contribute to this guide

News







Back to top

View this page

Edit this page


Toggle Light / Dark / Auto color theme


Toggle table of contents sidebar




Creating and packaging command-line tools¶

This guide will walk you through creating and packaging a standalone command-line application that can be installed with pipx, a tool for creating and managing Python Virtual Environments and exposing the executable scripts of packages (and available manual pages) for use on the command-line.


Creating the package¶

First of all, create a source tree for the project. For the sake of an example, we’ll build a simple tool outputting a greeting (a string) for a person based on arguments given on the command-line.


Todo

Advise on the optimal structure of a Python package in another guide or discussion and link to it here.


This project will adhere to src-layout and in the end be alike this file tree, with the top-level folder and package name greetings:


. ├── pyproject.toml └── src └── greetings ├── cli.py ├── greet.py ├── __init__.py └── __main__.py


The actual code responsible for the tool’s functionality will be stored in the file greet.py, named after the main module:


importtyperfromtyping_extensionsimportAnnotateddefgreet(name:Annotated[str,typer.Argument(help="The (last, if --title is given) name of the person to greet")]="",title:Annotated[str,typer.Option(help="The preferred title of the person to greet")]="",doctor:Annotated[bool,typer.Option(help="Whether the person is a doctor (MD or PhD)")]=False,count:Annotated[int,typer.Option(help="Number of times to greet the person")]=1):greeting="Greetings, "ifdoctorandnottitle:title="Dr."ifnotname:iftitle:name=title.lower().rstrip(".")else:name="friend"iftitle:greeting+=f"{title} "greeting+=f"{name}!"foriinrange(0,count):print(greeting)


The above function receives several keyword arguments that determine how the greeting to output is constructed. Now, construct the command-line interface to provision it with the same, which is done in cli.py:


importtyperfrom.greetimportgreetapp=typer.Typer()app.command()(greet)if__name__=="__main__":app()


The command-line interface is built with typer, an easy-to-use CLI parser based on Python type hints. It provides auto-completion and nicely styled command-line help out of the box. Another option would be argparse, a command-line parser which is included in Python’s standard library. It is sufficient for most needs, but requires a lot of code, usually in cli.py, to function properly. Alternatively, docopt makes it possible to create CLI interfaces based solely on docstrings; advanced users are encouraged to make use of click (on which typer is based).

Now, add an empty __init__.py file, to define the project as a regular import package.

The file __main__.py marks the main entry point for the application when running it via runpy (i.e. python-mgreetings, which works immediately with flat layout, but requires installation of the package with src layout), so initialize the command-line interface here:


if__name__=="__main__":fromgreetings.cliimportappapp()



Note

In order to enable calling the command-line interface directly from the source tree, i.e. as pythonsrc/greetings, a certain hack could be placed in this file; read more at Running a command-line interface from source with src-layout.



pyproject.toml¶

The project’s metadata is placed in pyproject.toml. The pyproject metadata keys and the [build-system] table may be filled in as described in Writing your pyproject.toml, adding a dependency on typer (this tutorial uses version 0.12.3).

For the project to be recognised as a command-line tool, additionally a console_scriptsentry point (see Creating executable scripts) needs to be added as a subkey:


[project.scripts]greet="greetings.cli:app"


Now, the project’s source tree is ready to be transformed into a distribution package, which makes it installable.




Installing the package with pipx¶

After installing pipx as described in Installing stand alone command line tools, install your project:


$ cdpath/to/greetings/ $ pipxinstall.


This will expose the executable script we defined as an entry point and make the command greet available. Let’s test it:


$ greet Greetings, friend!$ greet--doctorBrennan Greetings, Dr. Brennan!$ greet--titleMs.Parks Greetings, Ms. Parks!$ greet--titleMr. Greetings, Mr. mr!


Since this example uses typer, you could now also get an overview of the program’s usage by calling it with the --help option, or configure completions via the --install-completion option.

To just run the program without installing it permanently, use pipxrun, which will create a temporary (but cached) virtual environment for it:


$ pipxrun--spec.greet--doctor


This syntax is a bit impractical, however; as the name of the entry point we defined above does not match the package name, we need to state explicitly which executable script to run (even though there is only one in existence).

There is, however, a more practical solution to this problem, in the form of an entry point specific to pipxrun. The same can be defined as follows in pyproject.toml:


[project.entry-points."pipx.run"]greetings="greetings.cli:app"


Thanks to this entry point (which must match the package name), pipx will pick up the executable script as the default one and run it, which makes this command possible:


$ pipxrun.--doctor




Conclusion¶

You know by now how to package a command-line application written in Python. A further step could be to distribute your package, meaning uploading it to a package index, most commonly PyPI. To do that, follow the instructions at Packaging your project. And once you’re done, don’t forget to do some research on how your package is received!







Next

Creating and discovering plugins



Previous

Packaging namespace packages





Copyright © 2013–2020, PyPA
Made with Sphinx and @pradyunsg's Furo
Last updated on Jul 29, 2026







On this page



Creating and packaging command-line tools
Creating the package
pyproject.toml


Installing the package with pipx

Conclusion







------
导航页 打开网址