{"id":2832,"library":"types-qrcode","title":"Typing stubs for qrcode","description":"types-qrcode is a type stub package providing external type annotations for the 'qrcode' Python library. It enables static type checkers like Mypy and Pyright to analyze code that uses 'qrcode', ensuring type correctness without altering runtime behavior. This package is part of the Typeshed project, which releases updates frequently (sometimes daily) to maintain alignment with the 'qrcode' library's versions.","status":"active","version":"8.2.0.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","qrcode","typeshed","type-checking"],"install":[{"cmd":"pip install types-qrcode","lang":"bash","label":"Install types-qrcode for type checking"},{"cmd":"pip install qrcode[pil]","lang":"bash","label":"Install qrcode (runtime) with Pillow for image generation"}],"dependencies":[{"reason":"Provides the actual QR code generation functionality; types-qrcode only provides type hints for it.","package":"qrcode","optional":false},{"reason":"Required by the 'qrcode' library for saving QR codes as image files (e.g., PNG). Installed via 'qrcode[pil]'.","package":"Pillow","optional":true}],"imports":[{"note":"types-qrcode does not provide runtime functionality itself; imports are for the underlying 'qrcode' library.","symbol":"qrcode","correct":"import qrcode"},{"note":"Used for advanced control over QR code generation.","symbol":"QRCode","correct":"from qrcode import QRCode"},{"note":"Contains constants like error correction levels (e.g., ERROR_CORRECT_L).","symbol":"constants","correct":"from qrcode import constants"}],"quickstart":{"code":"import qrcode\n\n# Data to be encoded in the QR code\ndata = \"https://www.example.com/your-data-here\"\n\n# Create QR code instance with desired parameters\n# version: controls the size of the QR Code (1 to 40). None for auto-sizing.\n# error_correction: controls the error correction level.\n# box_size: size of each box (pixel) in the QR Code.\n# border: thickness of the border (minimum 4).\nqr = qrcode.QRCode(\n    version=1,\n    error_correction=qrcode.constants.ERROR_CORRECT_H, # High error correction\n    box_size=10,\n    border=4,\n)\n\n# Add data to the QR code\nqr.add_data(data)\nqr.make(fit=True)\n\n# Create an image from the QR code instance\n# Pillow (PIL) is required for saving as an image file like PNG\nimg = qr.make_image(fill_color=\"black\", back_color=\"white\")\n\n# Save the image\n# In a real application, you might use os.path.join for paths\noutput_filename = \"my_qrcode.png\"\nimg.save(output_filename)\n\nprint(f\"QR Code saved to {output_filename}\")","lang":"python","description":"This quickstart demonstrates how to generate and save a basic QR code using the 'qrcode' library. With 'types-qrcode' installed, a type checker would analyze this code for type correctness. The `qrcode[pil]` installation is crucial for the `img.save()` method to work correctly."},"warnings":[{"fix":"Ensure `qrcode` (and optionally `Pillow` via `qrcode[pil]`) is installed alongside `types-qrcode`.","message":"The `types-qrcode` package provides only type hints; it does not contain any runtime code. The actual `qrcode` library must be installed separately (e.g., `pip install qrcode`) for your application to function.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Keep `types-qrcode` updated to a version compatible with your installed `qrcode` library. Consider using version bounds (e.g., `types-qrcode>=8.2.0,<8.3`) in your `requirements.txt`.","message":"Type stubs are versioned to match the runtime library. If the `qrcode` library undergoes a major version update (e.g., from 8.x to 9.x), the `types-qrcode` stubs for the older version might become incompatible, leading to type-checking errors even if your runtime code still works.","severity":"breaking","affected_versions":"All versions, especially across major `qrcode` updates"},{"fix":"Install `qrcode` with the `pil` extra: `pip install qrcode[pil]`.","message":"For 'qrcode' to generate and save images (e.g., PNG, JPEG), the Pillow library is required. This is typically installed with `pip install qrcode[pil]`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Follow QR code design best practices: ensure high contrast (dark modules on a light background, 4:1 ratio minimum), maintain adequate size (at least 2x2 cm for close scans, 10:1 ratio for distance), and avoid excessive customization that obscures the pattern. Test thoroughly before deployment.","message":"Effective QR code usage involves design considerations (contrast, size, content). Type checkers won't flag poor design choices like low contrast (dark QR on dark background), inverted colors (light QR on dark background), or excessively small QR codes, which can severely impact scannability and user experience. Always test generated QR codes with multiple scanners.","severity":"gotcha","affected_versions":"All versions of qrcode and types-qrcode"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}