Text of packaging.python.org › en › latest › overview as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Overview of Python Packaging - Python Packaging User Guide

Skip to content Back to top View this page Edit this page Overview of Python Packaging ¶ As a general-purpose programming language, Python is designed to be used in many ways. You can build web sites or industrial robots or a game for your friends to play, and much more, all using the same core technology. Python’s flexibility is why the first step in every Python project must be to think about the project’s audience and the corresponding environment where the project will run.

It might seem strange to think about packaging before writing code, but this process does wonders for avoiding future headaches. This overview provides a general-purpose decision tree for reasoning about Python’s plethora of packaging options. Read on to choose the best technology for your next project. Thinking about deployment ¶ Packages exist to be installed (or deployed ), so before you package anything, you’ll want to have some answers to the deployment questions below: Who are your software’s users?

Will your software be installed by other developers doing software development, operations people in a datacenter, or a less software-savvy group? Is your software intended to run on servers, desktops, mobile clients (phones, tablets, etc.), or embedded in dedicated devices? Is your software installed individually, or in large deployment batches? Packaging is all about target environment and deployment experience. There are many answers to the questions above and each combination of circumstances has its own solutions.

With this information, the following overview will guide you to the packaging technologies best suited to your project. Packaging Python libraries and tools ¶ You may have heard about PyPI, setup.py , and wheel files. These are just a few of the tools Python’s ecosystem provides for distributing Python code to developers, which you can read about in Packaging and distributing projects . The following approaches to packaging are meant for libraries and tools used by technical audience in a development setting.

If you’re looking for ways to package Python for a non-technical audience and/or a production setting, skip ahead to Packaging Python applications . Python modules ¶ A Python file, provided it only relies on the standard library, can be redistributed and reused. You will also need to ensure it’s written for the right version of Python, and only relies on the standard library. This is great for sharing simple scripts and snippets between people who both have compatible Python versions (such as via email, StackOverflow, or GitHub gists).

There are even some entire Python libraries that offer this as an option, such as bottle.py and boltons . However, this pattern won’t scale for projects that consist of multiple files, need additional libraries, or need a specific version of Python, hence the options below. Python source distributions ¶ If your code consists of multiple Python files, it’s usually organized into a directory structure. Any directory containing Python files can comprise an Import Package .

Because packages consist of multiple files, they are harder to distribute. Most protocols support transferring only one file at a time (when was the last time you clicked a link and it downloaded multiple files?). It’s easier to get incomplete transfers, and harder to guarantee code integrity at the destination. So long as your code contains nothing but pure Python code, and you know your deployment environment supports your version of Python, then you can use Python’s native packaging tools to create a source Distribution Package , or sdist for short.

Python’s sdists are compressed archives ( .tar.gz files) containing one or more packages or modules. If your code is pure-Python, and you only depend on other Python packages, you can go to the Source distribution format specification to learn more. If you rely on any non-Python code, or non-Python packages (such as libxml2 in the case of lxml , or BLAS libraries in the case of numpy ), you will need to use the format detailed in the next section, which also has many advantages for pure-Python libraries.

Note Python and PyPI support multiple distributions providing different implementations of the same package. For instance the unmaintained-but-seminal PIL distribution provides the PIL package, and so does Pillow , an actively-maintained fork of PIL! This Python packaging superpower makes it possible for Pillow to be a drop-in replacement for PIL, just by changing your project’s install_requires or requirements.txt .

Python built distributions ¶ So much of Python’s practical power comes from its ability to integrate with the software ecosystem, in particular libraries written in C, C++, Fortran, Rust, and other languages. Not all developers have the right tools or experiences to build these components written in these compiled languages, so Python created the Wheel , a package format designed to ship libraries with compiled artifacts.

In fact, Python’s package installer, pip , always prefers wheels because installation is always faster, so even pure-Python packages work better with wheels. Built distributions are best when they come with source distributions to match. Even if you don’t upload wheels of your code for every operating system, by uploading the sdist, you’re enabling users of other platforms to still build it for themselves. Default to publishing both sdist and wheel archives together, unless you’re creating artifacts for a very specific use case where you know the recipient only needs one or the other.

Python and PyPI make it easy to upload both wheels and sdists together. Just follow the Packaging Python Projects tutorial. Python’s recommended built-in library and tool packaging technologies. Excerpted from The Packaging Gradient (2017) . ¶ Packaging Python applications ¶ So far we’ve only discussed Python’s native distribution tools. Based on our introduction, you would be correct to infer these built-in approaches only target environments which have Python, and an audience who knows how to install Python packages.

With the variety of operating systems, configurations, and people out there, this assumption is only safe when targeting a developer audience. Python’s native packaging is mostly built for distributing reusable code, called libraries, between developers. You can piggyback tools , or basic applications for developers, on top of Python’s library packaging, using technologies like setuptools entry_points . Libraries are building blocks, not complete applications.

For distributing applications, there’s a whole new world of technologies out there. The next few sections organize these application packaging options according to their dependencies on the target environment, so you can choose the right one for your project. Depending on a framework ¶ Some types of Python applications, like web site backends and other network services, are common enough that they have frameworks to enable their development and packaging.

Other types of applications, like dynamic web frontends and mobile clients, are complex enough to target that a framework becomes more than a convenience. In all these cases, it makes sense to work backwards, from the framework’s packaging and deployment story. Some frameworks include a deployment system which wraps the technologies outlined in the rest of the guide. In these cases, you’ll want to defer to your framework’s packaging guide for the easiest and most reliable production experience.

If you ever wonder how these platforms and frameworks work under the hood, you can always read the sections beyond. Service platforms ¶ If you’re developing for a “ Platform-as-a-Service ” or “PaaS”, you are going to want to follow their respective packaging guides. These types of platforms take care of packaging and deployment, as long as you follow their patterns. Most software does not fit one of these templa

The rest of this page is on the live site.