A lightweight, S3-compatible object storage server for local development, testing, and learning.
tiny-object-storage is a fast, minimalistic object storage server written in Python using FastAPI. It acts as a local emulator that mimics the core functionality of Amazon S3, allowing developers to test S3-integrated applications locally without relying on external cloud services or heavy containers like MinIO.
- S3 Compatibility: Supports core S3 XML responses and basic HTTP methods (
GET,PUT,HEAD,DELETE). - Bucket Management: Create, list, and delete buckets.
- Object Operations: Upload, download, metadata lookup, listing (
list-type=2), and deletion. - Persistent Storage: Filesystem-based persistence with dedicated metadata and data separation.
- Developer Experience: Interactive Swagger UI and OpenAPI schema built-in.
- Enterprise Code Quality: Enforced static typing (Mypy strict), linting (Ruff), and security analysis (Bandit).
- Flexible Configuration: Configurable via CLI arguments, environment variables, or
.envfiles.
From PyPI (Recommended)
Install the package globally or in a virtual environment using pip:
pip install tiny-object-storageFrom Source (Development) Clone the repository and install it in a virtual environment:
git clone https://github.com/EhsanBitaraf/tiny-object-storage.git
cd tiny-object-storage
python -m venv .venv
# On Linux/macOS:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate
# Install the application and development dependencies
pip install -e ".[dev]"Start the server using the built-in CLI:
tos-serverOr run it directly with uvicorn:
uvicorn tiny_object_storage.main:app --reload --host 0.0.0.0 --port 9000The server reads configuration in the following priority (highest to lowest):
- Command-line arguments
- Environment variables
.envfile
# View all available options
tos-server --help
# Load from a specific .env file
tos-server --env-file .env.custom
# Override host and port
tos-server --host 127.0.0.1 --port 9001 --reload
# Customize storage directories and log level
tos-server --data-dir ./storage_data --log-dir ./logs --log-level debugtiny-object-storage acts as a local emulator and has been successfully verified against the following official SDKs and tools:
- MinIO Python SDK
- Boto3 (AWS SDK for Python)
- AWS CLI
Note: For official SDKs to interact locally, configure them with
secure=False(or--no-verify-ssl) and point theendpoint_urltohttp://127.0.0.1:9000with any dummy credentials.
Sample scripts for verifying SDK interactions are included in the repository root (e.g., test_boto3_sdk.py, test_minio_sdk.py).
The project includes an extensive test suite built with pytest achieving 100% test pass rate over 63 edge-case scenarios.
pytest(Optionally, use pytest --cov=src to generate a coverage report).
We use pre-commit to maintain our code quality. The suite includes:
- Ruff: For ultra-fast linting and code formatting.
- Mypy: For strict static type checking.
- Bandit: For security vulnerability scanning.
To run checks manually on all files:
pre-commit run --all-filesAfter starting the server, visit /docs for the interactive Swagger UI. Below are standard curl examples targeting common S3 actions:
Health check
curl http://127.0.0.1:9000/healthCreate a bucket
curl -X PUT http://127.0.0.1:9000/photosUpload an object
curl -X PUT --data-binary @"cat.jpg" http://127.0.0.1:9000/photos/cat.jpgDownload an object
curl http://127.0.0.1:9000/photos/cat.jpg --output cat.jpgList objects (S3 Format)
curl "http://127.0.0.1:9000/photos?list-type=2"Debug endpoints (JSON format)
curl http://127.0.0.1:9000/_debug/buckets
curl http://127.0.0.1:9000/_debug/photosContributions are welcome and highly appreciated! Please review our Contributing Guidelines to get started. By participating in this project, you agree to abide by the Code of Conduct.
For instructions on reporting security vulnerabilities, please refer to our Security Policy.
This project is licensed under the MIT License - see the LICENSE file for details.