How can I create a local Python package that can be installed by pip?
- User
How can I create a local Python package that can be installed by pip?
- Assistant
Creating a local Python package that can be installed using
pipinvolves several steps, including organizing your code into a proper package structure, creating metadata files, building the package, and then installing it. Below are detailed instructions to guide you through this process.Step 1: Organize Your Package Structure
First, set up your project directory with the following structure:
your_project/ ├── LICENSE ├── README.md ├── pyproject.toml ├── setup.cfg ├── src/ │ └── your_package/ │ ├── __init__.py │ └── your_module.py └── tests/ └── test_your_module.pyHere's what each part is for:
LICENSE: (Optional) A text file containing the license for your package.README.md: A markdown file describing your package.pyproject.toml: Specifies build system requirements and package metadata.setup.cfg: Contains package configuration.src/your_package/: Directory containing your package code.__init__.py: An empty file that indicatesyour_packageis a Python package.your_module.py: Your Python modules (add more as needed).
tests/: (Optional) Directory containing your test suite.
Step 2: Create
pyproject.tomlThe
pyproject.tomlfile specifies the build system requirements and is now the standard way to declare project metadata (as per PEP 517 and PEP 518). Create apyproject.tomlfile in your project root with the following content:[build-system] requires = ["setuptools>=61.0", "wheel"] build-backend = "setuptools.build_meta"requires: Lists the packages needed to build your package (here,setuptoolsandwheel).build-backend: Specifies the build backend to use (setuptoolsin this case).
Step 3: Create
setup.cfgThe
setup.cfgfile contains metadata and options for your package. Create asetup.cfgfile with the following content:[metadata] name = your_package version = 0.1.0 author = Your Name author_email = your.email@example.com description = A short description of your package long_description = file: README.md long_description_content_type = text/markdown url = https://your.project.url license = MIT classifiers = Programming Language :: Python :: 3 License :: OSI Approved :: MIT License Operating System :: OS Independent [options] package_dir = = src packages = find: python_requires = >=3.6 install_requires = # List your package dependencies here, e.g., # numpy >= 1.21.0 include_package_data = True [options.packages.find] where = src [options.extras_require] testing = pytest >= 6.0 # Add other testing dependencies [options.entry_points] console_scripts = your-command = your_package.your_module:mainExplanation of key sections:
[metadata]: Contains metadata such as package name, version, author, etc.[options]:package_dir: Tellssetuptoolsto look for packages in thesrc/directory.packages: Specifies packages to include.find:tells it to find all packages underpackage_dir.python_requires: Specifies the Python versions your package is compatible with.install_requires: Lists runtime dependencies.include_package_data: Includes additional files specified inMANIFEST.in(if any).
[options.packages.find]: Configures package discovery.[options.extras_require]: Defines optional dependencies.[options.entry_points]: Defines console scripts for command-line interfaces.
Step 4: Write Your Package Code
In
src/your_package/__init__.py, you can initialize your package. For example:# src/your_package/__init__.py __version__ = "0.1.0" from .your_module import main # Import functions for convenienceIn
src/your_package/your_module.py, write your module code:# src/your_package/your_module.py def main(): print("Hello from your_package!")Step 5: Build the Package
First, ensure you have the necessary build tools installed:
pip install --upgrade buildThen, from the root of your project directory, run:
python -m buildThis command creates a
dist/directory containing the built distributions (a.tar.gzsource distribution and a.whlwheel file).Step 6: Install the Package Locally with
pipYou can now install your package locally using
pip. There are two methods:Method 1: Install from the Built Distributions
Install the package from the wheel file:
pip install dist/your_package-0.1.0-py3-none-any.whlOr from the source distribution:
pip install dist/your_package-0.1.0.tar.gzMethod 2: Install Directly from Source (Editable Install)
If you want to install the package in editable mode (useful during development), run:
pip install -e .The
-eor--editableoption tellspipto install the package in a way that changes to the source files are immediately available without reinstalling.Step 7: Verify the Installation
After installation, you can verify that your package is installed by trying to import it or running any console scripts you've defined.
Import the Package
Open a Python interpreter and try importing your package:
import your_package your_package.main()Use the Console Script
If you defined a console script entry point (as in the
setup.cfg), you can run it directly from the command line:your-commandThis should execute the
main()function inyour_package.your_module.Additional Tips
- Dependencies: In
setup.cfgunder[options], list any packages your package requires at runtime ininstall_requires. - Testing: Include your tests in the
tests/directory and list any testing dependencies under[options.extras_require]with a name liketesting. - Versioning: Manually update the version number in
setup.cfgunder[metadata]each time you make a new release. - License: If your package is for distribution, include a
LICENSEfile and specify the license insetup.cfg.
Resources
- Packaging Python Projects Tutorial - Official guide from the Python Packaging Authority.
- setuptools Documentation - Detailed information on using
setuptoolsfor packaging. - PEP 517 – A build-system independent format for source trees
- PEP 518 – Specifying Minimum Build System Requirements for Python Projects
By following these steps, you will have created a local Python package that can be installed using
pip. This approach is suitable for managing dependencies in a consistent way and makes it easier to share your package with others, even if you don't publish it to the Python Package Index (PyPI).