A powerful, easy-to-use Python package for generating professional QR codes with customizable styling, watermark/logo support, and multiple output formats.
QR Code Generator enables you to quickly create QR codes from URLs or plain text with full control over appearance and branding. Perfect for marketing materials, product packaging, event management, and more.
Key Highlights:
- 🎨 Fully customizable colors and styling
- 🏷️ Built-in watermark/logo support with automatic scaling
- 📦 Easy installation from PyPI
- 🖥️ Both CLI and Python API
- 💾 Multiple output formats (PNG, JPG, JPEG)
- 🔧 Simple, intuitive interface
- ✅ Generate QR codes from URLs or plain text
- ✅ Customize size, foreground/background colors, and error correction level
- ✅ Add watermark/logo with automatic centering and scaling
- ✅ Save to PNG/JPG/JPEG formats
- ✅ Command-line interface (CLI) for quick generation
- ✅ Python API for programmatic use
- ✅ Packaged and published on PyPI
- ✅ Project metadata and build configuration via
pyproject.toml - ✅ Supports error correction levels (L, M, Q, H)
- ✅ Automatic output directory creation
- Python >= 3.8
- Dependencies:
qrcode[pil],Pillow
pip install qr-generator-cliInstall the latest development version from the repository:
pip install git+https://github.com/Ahmed122000/QR-Code-Generator.gitClone the repository and install in editable mode:
git clone https://github.com/Ahmed122000/QR-Code-Generator.git
cd QR-Code-Generator
pip install -e .The simplest way to generate QR codes:
# Basic: generate and save to qrcode.png
qr "https://example.com" --output qrcode.png
# With custom styling
qr "https://example.com" --size 800 --fg "#1d3557" --bg "#f1faee" --ec H
# Add a watermark/logo
qr "https://example.com" --output qrcode.png --watermark assets/logo.png --watermark-scale 0.25
# Plain text input
qr "Hello, World!" --output text-qr.png
# High error correction
qr "https://example.com" --size 600 --ec H --output secure-qr.pngFor programmatic QR code generation:
from qr_generator import QRGenerator
# Create a QR code generator instance
gen = QRGenerator()
# Generate and save a QR code
gen.make_qr(
data="https://example.com",
output_path="qrcode.png"
)
# With custom styling
gen.make_qr(
data="https://example.com",
output_path="styled_qr.png",
size=800,
fg_color="#1d3557",
bg_color="#f1faee",
error_correction="H"
)
# With watermark/logo
gen.make_qr(
data="https://example.com",
output_path="branded_qr.png",
watermark_path="assets/logo.png",
watermark_scale=0.25
)Usage: qr [OPTIONS] DATA
Arguments:
DATA The URL or text to encode in the QR code
Options:
--output, -o Output file path (default: qrcode.png)
--size QR code size in pixels (default: 400)
--fg, --foreground Foreground color as hex code (default: #000000)
--bg, --background Background color as hex code (default: #FFFFFF)
--ec, --error-correction Error correction level: L, M, Q, H (default: M)
--watermark Path to watermark/logo image file
--watermark-scale Watermark scale relative to QR code (default: 0.2)
--help Show help message
| Level | Recovery | Use Case |
|---|---|---|
| L | ~7% | Low-traffic environments |
| M | ~15% | Standard use (recommended) |
| Q | ~25% | Partially obscured codes |
| H | ~30% | Highly damaged/outdoor use |
Colors should be specified as hexadecimal values:
#000000(black)#FFFFFF(white)#FF5733(custom colors)
from qr_generator import QRGenerator
gen = QRGenerator()
gen.make_qr("https://github.com/Ahmed122000", output_path="github_qr.png")from qr_generator import QRGenerator
gen = QRGenerator()
gen.make_qr(
data="https://yourcompany.com",
output_path="company_qr.png",
size=600,
fg_color="#2C3E50",
bg_color="#ECF0F1",
watermark_path="company_logo.png",
watermark_scale=0.3,
error_correction="H"
)from qr_generator import QRGenerator
import csv
gen = QRGenerator()
# Read URLs from CSV and generate QR codes
with open("urls.csv", "r") as f:
reader = csv.DictReader(f)
for row in reader:
gen.make_qr(
data=row["url"],
output_path=f"output/{row['name']}_qr.png",
size=500,
fg_color="#1d3557",
bg_color="#f1faee"
)- CLI Interface — Command-line argument parsing via
argparsewith flexible input options - QR Generation — Leverages the
qrcodelibrary for reliable QR encoding - Image Processing — Uses Pillow (PIL) for image manipulation
- Watermarking — Custom logo/watermark scaling and centering with transparency preservation
- Output — Supports PNG, JPG, and JPEG formats with high quality
User Input (URL/Text)
↓
Validation & Normalization
↓
QR Code Generation (qrcode library)
↓
Watermark Processing (if provided)
↓
Image Conversion (if needed)
↓
File Output
QR-Code-Generator/
├── src/
│ ├── main.py # CLI entry point
│ ├── qr_generator.py # Core QR generation logic
│ └── utils.py # Utility functions
├── examples/
│ ├── basic.py # Simple QR generation
│ ├── with_logo.py # Watermark/logo example
│ └── batch_generate.py # Batch processing example
├── assets/
│ ├── output/ # Sample output directory
│ └── logo.png # Sample logo for examples
├── tests/ # Unit tests
├── pyproject.toml # Package configuration
├── README.md # This file
├── LICENSE # MIT License
└── .gitignore # Git ignore rules
ImportError: No module named 'qrcode'
pip install qrcode[pil] PillowPermissionError: Permission denied creating output directory
- Ensure you have write permissions in the target directory
- Try creating the output directory manually:
mkdir -p output
Watermark not displaying
- Verify the watermark file path exists and is readable
- Use PNG format with transparency for best results
- Check watermark-scale is between 0.1 and 0.5
Invalid color format
- Ensure colors are specified as hex values:
#RRGGBB - Example:
#FF5733(notrgb(255, 87, 51))
QR code not scannable
- Try increasing error correction level:
--ec H - Increase QR code size:
--size 600or higher - Ensure sufficient contrast between foreground and background colors
- ✨ Initial release
- 📦 Published to PyPI as
qr-generator-cli - 🎨 Full customization support
- 🏷️ Watermark/logo feature
- 🖥️ CLI and Python API
For detailed release notes, see CHANGELOG.md (if available).
We welcome contributions! Here's how to get started:
- Fork the repository on GitHub
- Create a feature branch:
git checkout -b feature/your-feature-name - Make your changes and commit:
git commit -m "Add your feature" - Write/update tests to cover your changes
- Push to your fork:
git push origin feature/your-feature-name - Open a Pull Request with a clear description of your changes
# Install in development mode
pip install -e ".[dev]"
# Run tests
python -m pytest
# Run linting
pylint src/
# Format code
black src/Found a bug? Please open an issue with:
- Clear description of the problem
- Steps to reproduce
- Expected vs. actual behavior
- Python version and OS information
- QR Code Size: Larger QR codes (800x800px) take slightly longer to generate but are easier to scan
- Watermark Processing: Watermarked codes take ~10-20% longer due to image compositing
- Batch Operations: For generating 100+ codes, consider using threading or async patterns
- Input Validation: URLs and text are validated before QR encoding
- File Permissions: Output files are created with standard user permissions
- No External Calls: All processing is local; no data is sent to external services
- Maximum data capacity: ~2953 bytes (depends on error correction level)
- Watermarks should be <= 30% of QR code size for optimal scanability
- Recommended minimum QR code size: 200x200 pixels
This project is licensed under the MIT License — see the LICENSE file for details.
You are free to use, modify, and distribute this software, provided you include the original copyright notice and license.
- Built with qrcode
- Image processing powered by Pillow
- Inspired by the need for simple, professional QR code generation
- 📖 Documentation: See examples and features above
- 🐛 Bug Reports: GitHub Issues
- 💬 Discussions: GitHub Discussions
Ahmed122000
GitHub: @Ahmed122000
Made with ❤️ for the open-source community
If you find this project useful, please consider giving it a ⭐ on GitHub!