OpenStack Swift: the object store behind Rackspace's Cloud Files

The problem Swift solves, and who feels it

Object storage that starts on one box and has to keep working on a thousand is a different design problem from a filesystem that grows. Swift's README states the target directly: a distributed object storage system designed to scale from a single machine to thousands of servers, optimized for multi-tenancy and high concurrency. The stated workloads are backups, web and mobile content, and unstructured data that can grow without bound.

That framing matters for who should read further. If you are storing a few terabytes behind one application and nobody else shares the cluster, Swift's multi-tenancy machinery is overhead you will pay for and never use. If you are the storage team for a platform where many projects or customers each need isolated containers, isolated quotas and an API that client libraries already implement, the multi-tenant design is the reason to pick this over a simpler store.

The project has a lineage that explains its shape. According to the README, Swift was originally developed as the basis for Rackspace's Cloud Files and was open-sourced in 2010 as part of OpenStack. It has since grown to include contributions from many companies. That history is why the API is REST-based and documented separately from the server implementation, and why the client story is split out into python-swiftclient rather than living in this repository.

How a request moves through the proxy, account, container and object servers

The README's Data Flow section is unusually concrete for a project of this age, and it is the fastest way to understand the architecture. Swift is a WSGI application and uses eventlet's WSGI server. Once the processes are running, the entry point for new requests is the Application class in swift/proxy/server.py. From there a controller is chosen and the request is processed. The proxy may forward the request to a back-end server; the entry point for object server requests is the ObjectController class in swift/obj/server.py.

So the proxy is not a load balancer in front of an opaque blob store. It is the component that understands the API, picks a controller, and decides which back-end server should handle the request. The repository layout mirrors this split: swift/account/, swift/container/, swift/obj/ and swift/proxy/ each hold a server, swift/common/ holds code shared by the modules, and swift/common/ring/ holds the ring implementation. The ring is the piece that maps what a client asks for onto which servers hold it, which is what lets the cluster grow without the proxy holding a central directory.

Two other directories are worth knowing before you deploy. swift/common/middleware/ holds what the README calls the standard, officially supported middleware. Anything outside that directory is a third-party concern, and the README points to an associated projects page for the wider ecosystem. The etc/ directory holds sample config files, and examples/ holds config snippets used in the docs, so the configuration you copy into production has a reference version in the tree.

Installing Swift and running your first real cluster

The README does not give a production install procedure. It gives developer instructions and points deployers at the online deployment guide, so treat the steps below as the developer path the project itself recommends, not a production recipe.

The README says the best place to get started is the SAIO, Swift All In One document, which walks you through setting up a development cluster of Swift in a VM. The SAIO environment is described as ideal for running small-scale tests against Swift and trying out new features and bug fixes. There is a Dockerfile in the repository root that builds an Alpine 3.16.2 Swift All In One image, which is the fastest route if you would rather not build a VM by hand.

If you want the source tree and its documentation locally, the README gives these commands:

pip install -r requirements.txt -r doc/requirements.txt
sphinx-build -W -b html doc/source doc/build/html

After that, browse to doc/build/html/index.html. The documentation is auto-generated after every commit and also available online at docs.openstack.org/swift/latest.

Once a cluster exists, the README describes three test types and the scripts that run them. Unit tests check small sections of code, functional tests check that the client API works as expected against any endpoint claiming to support the Swift API, and probe tests are white box tests that validate the internal workings of a cluster. The scripts are named after the test type:

.unittests
.functests
.probetests
.alltests

The README warns that running the tests fully requires a filesystem supporting large xattrs, strongly recommends XFS, and notes that for unit tests and in-process functional tests you should either mount /tmp with XFS or provide another XFS filesystem via the TMPDIR environment variable. Without it, the README says tests should still pass but a very large number will be skipped. Functional tests against a cluster need /etc/swift/test.conf, and a sample config file lives in the source tree at test/sample.conf.

Where Swift is the wrong tool

The most honest limitation is the one the README states as a recommendation rather than a warning. To fully run the test suite you need a filesystem that supports large xattrs, and XFS is strongly recommended. That is a constraint on the machines running Swift, not just on the test host, and it is the kind of requirement that surfaces late if you assume a default filesystem is fine.

The second limitation is structural. Swift is a multi-process, multi-role system: proxy, account, container and object servers, each with its own entry point, plus a ring that has to be built and distributed. The README's own answer to a new deployer is to stand up a VM first. If your workload fits comfortably on one machine and you do not need per-tenant isolation or an HTTP object API, the proxy and ring layers are cost with no return.

The third is that this repository is a mirror. The description states it is a mirror of code maintained at opendev.org, and the README's contributor notes point at the OpenStack contribution, review and testing processes rather than a GitHub pull request flow. If your team's habit is to fork and patch in place, that habit works against you here. Finally, the README does not document rollback or downgrade procedures, so you should not assume one exists without checking the ops runbook.

Swift against a filesystem-backed object store

The obvious alternative for someone who wants an S3-compatible endpoint without running a distributed system is MinIO, which presents itself as a single binary and an S3 API. The difference in approach is not cosmetic. MinIO's unit of deployment is a process you start; Swift's unit of deployment is a set of server roles plus a ring that has to be built and kept in sync across nodes. Swift's README does not claim S3 compatibility at all. It documents a REST-based API at docs.openstack.org/api-ref/object-store and provides official Python bindings separately at python-swiftclient.

That split cuts both ways. If your applications already speak S3, Swift is a migration project. If your applications are written against the Swift API, or you are inside an OpenStack deployment where Swift is the object store the rest of the platform expects, the separate API and the separate client library are the point, not a defect.

The second real alternative is doing nothing: keeping objects on a shared filesystem or a NAS. That works until you need multi-tenancy or high concurrency across many clients, which is exactly the case the README names as Swift's target. The trade is that you give up POSIX semantics for an HTTP API and a ring.

Maintenance, upgrade cost and the Apache-2.0 licence

The repository is not archived and the last push was on 2026-09-24, so this is code that is still receiving commits. Do not read that as a stability guarantee for your deployment: the README describes documentation auto-generated after every commit, which tells you the project moves continuously rather than in the release-and-freeze rhythm some operators prefer. There are no releases listed for this repository, so plan your upgrade path around the branch and the deployment guide rather than around a versioned tarball.

The upgrade cost you should budget for is the ring. Because the proxy decides where a request goes based on ring data, and the ring is built from the server layout, changing your cluster topology is an operation with its own procedure, not a config reload. The README points deployers at an ops runbook for diagnosing and troubleshooting common issues when running a Swift cluster. Read that before you need it, not during an incident.

On licensing, the repository carries Apache-2.0. The requirements file lists dependencies under their own terms, including eventlet under MIT, PyECLib under BSD, cryptography under BSD or Apache-2.0, and dnspython under its own licence. If your organisation has a dependency review process, that file is the list to hand it. Nothing here is legal advice; check the licence texts and your own obligations.

Editorial conclusion

Adopt Swift if you need a multi-tenant object store with a documented ops runbook and a REST API that third-party tools already speak, and you are willing to run the SAIO VM first to learn the moving parts. Do not adopt it if you want a single binary with no proxy, ring or account/container/object split to reason about. Before committing, verify the deployment guide against your own hardware, confirm your filesystem supports the large xattrs the test suite needs, and check whether the middleware you depend on is in swift/common/middleware/ or shipped by a third party.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. openstack/swift on GitHub
4. Project website
5. README