[!TIP] PyShotter - Smart, annotated, and shareable screenshots for Python.
from pyshotter import pyshotter
# The simplest use, save a screenshot of the 1st monitor
with pyshotter() as sct:
sct.shot()
An ultra-fast cross-platform screenshot library that makes it easy to capture, annotate, and share screenshots from your Python code.
python -m pip install -U --user pyshotter
For enhanced features, install additional dependencies:
# For OCR and advanced image processing
python -m pip install pyshotter[ocr]
# For annotation features
python -m pip install pyshotter[annotation]
# For sharing features
python -m pip install pyshotter[sharing]
# For cloud upload capabilities
python -m pip install pyshotter[cloud]
# For development
python -m pip install pyshotter[dev]
from pyshotter import pyshotter
# Take a screenshot of the first monitor
with pyshotter() as sct:
sct.shot()
# Take screenshots of all monitors
with pyshotter() as sct:
for i, monitor in enumerate(sct.monitors):
sct.shot(mon=i)
from pyshotter import pyshotter, SmartDetectionFeature, OCRFeature
with pyshotter() as sct:
screenshot = sct.grab(sct.monitors[0])
# Detect code regions and windows
detector = SmartDetectionFeature()
code_regions = detector.detect_code_regions(screenshot)
windows = detector.detect_windows(screenshot)
print(f"Found {len(code_regions)} code regions")
print(f"Found {len(windows)} windows")
# Extract text using OCR
ocr = OCRFeature()
text = ocr.extract_text(screenshot)
print(f"Extracted text: {text}")
from pyshotter import pyshotter, AnnotationFeature
with pyshotter() as sct:
screenshot = sct.grab(sct.monitors[0])
# Initialize annotation
annotator = AnnotationFeature()
# Add text annotation
annotated = annotator.add_text(
screenshot,
"Important Code Here!",
(100, 100),
font_size=24,
color=(255, 0, 0) # Red text
)
# Add rectangle around a region
annotated = annotator.add_rectangle(
annotated,
(50, 50), # Top-left corner
(400, 200), # Bottom-right corner
color=(0, 255, 0), # Green rectangle
thickness=3
)
# Add arrow pointing to something
annotated = annotator.add_arrow(
annotated,
(150, 150), # Start point
(300, 100), # End point
color=(0, 0, 255), # Blue arrow
thickness=2
)
# Add circle highlight
annotated = annotator.add_circle(
annotated,
(200, 150), # Center point
30, # Radius
color=(255, 255, 0), # Yellow circle
thickness=2
)
# Add highlight overlay
annotated = annotator.add_highlight(
annotated,
(100, 100, 200, 100), # (x, y, width, height)
color=(255, 255, 0), # Yellow highlight
alpha=0.3 # 30% transparency
)
# Save the annotated screenshot
annotated.save("annotated_screenshot.png")
from pyshotter import pyshotter, SharingFeature
with pyshotter() as sct:
screenshot = sct.grab(sct.monitors[0])
# Initialize sharing
sharer = SharingFeature()
# Copy to clipboard
if sharer.copy_to_clipboard(screenshot):
print("Screenshot copied to clipboard!")
# Generate shareable link
link = sharer.generate_shareable_link(screenshot)
print(f"Shareable link: {link}")
# Save with metadata
metadata = {
"title": "My Screenshot",
"description": "Screenshot taken with PyShotter",
"tags": ["python", "screenshot", "demo"],
"author": "Abdoullah Ndao",
"timestamp": "2024-12-19"
}
sharer.save_with_metadata(screenshot, "screenshot.png", metadata)
from pyshotter import pyshotter, RedactionFeature
with pyshotter() as sct:
screenshot = sct.grab(sct.monitors[0])
# Initialize redaction
redaction = RedactionFeature()
# Redact sensitive data
clean_screenshot = redaction.redact_sensitive_data(screenshot)
clean_screenshot.save("clean_screenshot.png")
from pyshotter import pyshotter, PanoramaFeature
with pyshotter() as sct:
# Capture all monitors
screenshots = []
for monitor in sct.monitors:
screenshot = sct.grab(monitor)
screenshots.append(screenshot)
# Create panoramic image
panorama = PanoramaFeature()
panoramic_screenshot = panorama.create_panorama(screenshots)
panoramic_screenshot.save("panorama.png")
import time
from pyshotter import pyshotter, ChangeDetectionFeature
with pyshotter() as sct:
# Take first screenshot
previous = sct.grab(sct.monitors[0])
# Wait for changes
time.sleep(5)
# Take second screenshot
current = sct.grab(sct.monitors[0])
# Detect changes
detector = ChangeDetectionFeature()
changes = detector.detect_changes(current, previous, threshold=0.1)
changes.save("changes.png")
from pyshotter import pyshotter, ScreenshotHistory
# Initialize history manager
history = ScreenshotHistory()
with pyshotter() as sct:
screenshot = sct.grab(sct.monitors[0])
# Add to history with metadata
screenshot_id = history.add_screenshot(
screenshot,
metadata={
"tags": ["desktop", "work"],
"window_title": "Example Window",
"description": "Sample screenshot for demonstration"
}
)
# Search history
results = history.search_history("work")
for result in results:
print(f"Found: {result['id']} - {result['timestamp']}")
pyshotter(**kwargs)Factory function that returns a platform-specific screenshot instance.
Parameters:
mon (int): Monitor index (default: 0)output (str): Output filename patternwith_cursor (bool): Include cursor in screenshotcompression_level (int): PNG compression level (0-9)Returns:
sct.shot(**kwargs)Take a screenshot and save it to a file.
Parameters:
mon (int): Monitor index or monitor dictoutput (str): Output filenamewith_cursor (bool): Include cursorReturns:
sct.grab(monitor)Capture a screenshot without saving.
Parameters:
monitor (dict): Monitor configurationReturns:
SmartDetectionFeature.detect_code_regions(screenshot)Detect code-like regions in screenshots.
Parameters:
screenshot (ScreenShot): Screenshot to analyzeReturns:
SmartDetectionFeature.detect_windows(screenshot)Detect application windows in screenshots.
Parameters:
screenshot (ScreenShot): Screenshot to analyzeReturns:
AnnotationFeature.add_text(screenshot, text, position, font_size, color)Add text annotation to a screenshot.
Parameters:
screenshot (ScreenShot): Screenshot to annotatetext (str): Text to addposition (tuple): (x, y) positionfont_size (int): Font sizecolor (tuple): RGB color tupleReturns:
AnnotationFeature.add_rectangle(screenshot, top_left, bottom_right, color, thickness)Add rectangle annotation to a screenshot.
Parameters:
screenshot (ScreenShot): Screenshot to annotatetop_left (tuple): Top-left corner (x, y)bottom_right (tuple): Bottom-right corner (x, y)color (tuple): RGB color tuplethickness (int): Line thicknessReturns:
SharingFeature.copy_to_clipboard(screenshot)Copy screenshot to system clipboard.
Parameters:
screenshot (ScreenShot): Screenshot to copyReturns:
SharingFeature.generate_shareable_link(screenshot, service)Generate a shareable link for the screenshot.
Parameters:
screenshot (ScreenShot): Screenshot to shareservice (str): Sharing service nameReturns:
from pyshotter import pyshotter
# Simple screenshot
with pyshotter() as sct:
sct.shot()
# Screenshot with cursor
with pyshotter(with_cursor=True) as sct:
sct.shot()
# Screenshot of specific monitor
with pyshotter() as sct:
sct.shot(mon=1) # Second monitor
from pyshotter import pyshotter, AnnotationFeature, SharingFeature
with pyshotter() as sct:
# Capture screenshot
screenshot = sct.grab(sct.monitors[0])
# Annotate
annotator = AnnotationFeature()
annotated = annotator.add_text(screenshot, "Hello World!", (100, 100))
annotated = annotator.add_rectangle(annotated, (50, 50), (300, 200))
# Share
sharer = SharingFeature()
sharer.copy_to_clipboard(annotated)
# Save
annotated.save("final_screenshot.png")
git clone https://github.com/utachicodes/pyshotter.git
cd pyshotter
python -m pip install -e ".[dev]"
python -m pytest
# Format code
ruff format src/
# Lint code
ruff check src/
# Type checking
mypy src/
# Run all checks
ruff check src/ && mypy src/ && python -m pytest
We welcome contributions! Please see our Contributing Guide for details.
This project is licensed under the MIT License - see the LICENSE.txt file for details.
Abdoullah Ndao - GitHub - abdoullahaljersi@gmail.com
PyShotter - Making screenshots smart, annotated, and shareable!
FAQs
PyShotter: Smart, annotated, and shareable screenshots for Python.
We found that pyshotter demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Application Security
/Security News
Socket CEO Feross Aboukhadijeh and a16z partner Joel de la Garza discuss vibe coding, AI-driven software development, and how the rise of LLMs, despite their risks, still points toward a more secure and innovative future.
Research
/Security News
Threat actors hijacked Toptal’s GitHub org, publishing npm packages with malicious payloads that steal tokens and attempt to wipe victim systems.
Research
/Security News
Socket researchers investigate 4 malicious npm and PyPI packages with 56,000+ downloads that install surveillance malware.