Recommended Free Tools
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
pyautogui.locate(needleImage, haystackImage) finds a smaller reference image inside a larger image you provide. To find that reference on the live display instead, use pyautogui.locateOnScreen(image). Both first-match functions return a box containing the match’s left, top, width, and height; use pyautogui.center(box) when you need a click point.
This guide covers image-file searches, screen searches, matching options, result handling, and common reasons a match fails. PyAutoGUI’s official screenshot documentation and quickstart disagree about what happens when no match is found, so the examples handle the documented exception and explain how to check behavior in your installed version.
What locate searches—and what it returns
PyAutoGUI’s locate functions use image matching: give them a small image to find (the needle) and a larger image or screen to search (the haystack). The official documentation distinguishes locate, which searches images you supply, from locateOnScreen, which obtains the current screen image and searches it. See the PyAutoGUI screenshot functions documentation.
locate(needleImage, haystackImage)returns the first matching rectangle in the supplied haystack image.locateOnScreen(image)returns the first matching rectangle on the screen.locateAllandlocateAllOnScreenyield rectangles for all matches rather than just the first.locateCenterOnScreenreturns the center point of the first screen match.
A rectangle is represented as (left, top, width, height). It supports tuple-style indexing and named fields such as .left. The point returned by pyautogui.center(box) has .x and .y fields. Coordinates for screen searches are screen coordinates, so the point can be passed to PyAutoGUI mouse functions.
#1 Best Overall
Find a template inside an image file
Use locate when both the reference and search area are image files or image objects that PyAutoGUI can read. The first argument is the smaller reference; the second is the larger image to inspect.
import pyautogui
# needle.png is the small image to find inside haystack.png.
box = pyautogui.locate("needle.png", "haystack.png")
print(box) # Box(left=..., top=..., width=..., height=...)
# A box is (left, top, width, height).
left, top, width, height = box
print("top-left:", left, top)
print("size:", width, height)
center = pyautogui.center(box)
print("center:", center.x, center.y)The returned box describes the match’s position and dimensions within the haystack image. This is useful when you want to inspect an existing screenshot, test matching against a saved image, or separate image analysis from live mouse automation. locate does not itself click or move the pointer.
If you want to search the current display, use locateOnScreen instead. Passing a filename is the common pattern; the screenshot functions documentation also describes accepting image data.
Find an image on the screen and act on it
Capture the target control as a small reference image, then search the screen. If you intend to click the match, convert its box to a center point first:
import pyautogui
try:
box = pyautogui.locateOnScreen("button.png")
except pyautogui.ImageNotFoundException:
print("Button image was not found")
else:
point = pyautogui.center(box)
pyautogui.click(point.x, point.y)The official screenshot page says the locate family raises ImageNotFoundException if an image cannot be found and identifies that behavior as applying since PyAutoGUI 0.9.41. However, the official quickstart says a missing image returns None. Because those official pages conflict, check the behavior and exception namespace for the version actually installed in your environment rather than assuming a None check is sufficient. The example follows the screenshot page’s exception guidance; it is not a guarantee for every release or installation.
PyAutoGUI also documents a convenience shortcut, pyautogui.click('button.png'), which searches for that image on screen and clicks its center. Use it only when clicking the first matching control is intended. The explicit locate-then-click form makes it easier to handle a missing match, inspect coordinates, add logging, or verify a result before taking action.
Choose the right locate function
| Function | Search target | Result |
|---|---|---|
locate(needleImage, haystackImage) |
A supplied larger image | First matching box |
locateAll(needleImage, haystackImage) |
A supplied larger image | Iterable of matching boxes |
locateOnScreen(image) |
Current screen | First matching box |
locateAllOnScreen(image) |
Current screen | Iterable of matching boxes |
locateCenterOnScreen(image) |
Current screen | Center point of first match |
Use a first-match function when one occurrence is enough. If the same icon can appear more than once and you need to choose among occurrences, use an all-match function and inspect each box. These functions yield boxes, not center points; call pyautogui.center(box) for a click coordinate.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsimport pyautogui
try:
matches = list(pyautogui.locateAllOnScreen("icon.png"))
except pyautogui.ImageNotFoundException:
matches = []
for box in matches:
point = pyautogui.center(box)
print("match box:", box, "click point:", (point.x, point.y))As with the first-match calls, confirm how the installed release reports no matches. The documentation discrepancy applies to the locate family, and a generator’s iteration can be where searching occurs; handle the documented exception around iteration as shown.
Adjust matching with confidence, region, and grayscale
Use confidence when pixels are not an exact match
By default, image matching is exact enough that small visual changes can prevent a match. The screenshot documentation shows a confidence argument, for example confidence=0.9, to allow less exact matches. That option requires OpenCV to be installed. A lower threshold can help with modest rendering differences, but it can also make unrelated visual content more likely to qualify.
import pyautogui
box = pyautogui.locateOnScreen("button.png", confidence=0.9)Install and configure OpenCV in the Python environment running the script if you use confidence. If the call rejects the argument or reports a missing dependency, consult the official PyAutoGUI installation instructions and the instructions for the OpenCV package available for your platform. The documentation consulted does not establish current package versions or platform-specific installation status.
Restrict the screen search with a region
When you know roughly where the target appears, pass region=(left, top, width, height) to a screen-search function. The coordinates and dimensions describe the portion of the screen to inspect:
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →import pyautogui
# Search only a 500-by-300-pixel area starting at (100, 120).
box = pyautogui.locateOnScreen(
"button.png",
region=(100, 120, 500, 300),
)A restricted region can improve search speed, and the documentation recommends it as the best way to speed up screen matching. Make sure the region includes the whole possible target location; a control outside it cannot be found by that call.
Trade color detail for grayscale speed cautiously
Set grayscale=True to ignore color information during matching. PyAutoGUI’s documentation estimates a speed improvement of roughly 30%, but calls it an approximate trade-off: losing color distinctions can create false-positive matches. Keep the default color-aware behavior when similarly shaped controls differ mainly by color, or when a wrong match could trigger an unwanted action.
box = pyautogui.locateOnScreen("button.png", grayscale=True)For screen functions, the options can be combined where supported, for example using a known region and grayscale together. Test any relaxed or color-blind matching against the interface states your automation will actually encounter.
Make a useful reference image
A successful search depends on the reference looking like the target as it is rendered in the haystack or on screen. A reference cut from a different display scale, theme, or interface state may no longer match the same control. Capture the reference from the same visual conditions where possible, and include enough distinctive detail to distinguish it from nearby controls without including unnecessary surrounding content.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallRank #4
- Check that the template is the correct file and opens as expected.
- Keep the template focused on the element you want to recognize; avoid including changing text, animation, or nearby content.
- Confirm the application is showing the expected state before searching.
- When using a screen region, verify its origin and dimensions against screen coordinates.
- When using
confidenceor grayscale, inspect the returned location before an irreversible action.
These are practical checks rather than guarantees of detection: image matching depends on visible pixels, and the official documentation does not promise recognition across arbitrary scaling or visual changes.
Performance and reliability
Screen matching can take long enough to matter in automation loops. PyAutoGUI’s documentation gives roughly one to two seconds for locate calls on a 1920×1080 screen. That is a documentation estimate, not a benchmark for every computer, display, image, or software version. The same documentation warns that this can be too slow for action video games.
- Prefer a bounded
regionwhen the target’s location is predictable. - Search only as often as the workflow requires; avoid repeatedly scanning the full display without a reason.
- Use grayscale only if its speed trade-off is acceptable and false positives have been considered.
- For actions with consequences, verify a match and its location before clicking rather than treating a visual match as proof of application state.
For dependable automation, decide what the script should do when the target is absent, appears more than once, or is found at an unexpected location. Handle those cases explicitly; a successful image match is not the same thing as confirming that an application operation completed.
Install and platform context
PyAutoGUI’s screenshot functionality depends on Pillow. The official installation page describes platform-specific setup and mentions Linux packages such as scrot and Tkinter. Those instructions were crawled several years ago, so current releases and exact prerequisites may differ. Check the installation page for your operating system and environment before diagnosing a capture failure as an image-matching problem.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Also make sure the Python interpreter that runs the script is the one in which PyAutoGUI and its screenshot dependencies were installed. A package installed in a different virtual environment will not necessarily be available to the process running your automation.
Best Value
Troubleshoot common locate problems
| Symptom | Likely cause | What to try |
|---|---|---|
| No match is reported, or an exception is raised | The target is not visible, the reference differs from the rendered target, or the search region excludes it. | Check the current screen and reference file, search without a region to test the region assumption, and handle the missing-match behavior documented for your installed version. |
confidence is rejected or unavailable |
OpenCV is not available in the active Python environment, or the installed combination does not support the option. | Check the environment and the installation instructions; try the default exact search to separate dependency issues from template mismatch. |
| The script raises a screenshot-related dependency error | Pillow or a platform screenshot prerequisite may be missing or unavailable. | Follow the official installation page for the operating system; on Linux, check its listed screenshot and Tkinter setup context. |
| The wrong similar-looking item is found | A loose confidence threshold or grayscale matching may have removed useful distinctions. | Use the default color-aware matching, choose a more distinctive template, or narrow the region. |
| Searches feel slow | The call is examining a large screen area or running too frequently. | Limit the search region and reduce unnecessary repeated scans. Treat the documentation’s timing as an estimate, not a local performance guarantee. |
| A click lands somewhere unexpected | The box or center was interpreted incorrectly, multiple matches exist, or the display state changed between search and click. | Print the box and center, inspect all matches when necessary, and verify the target remains in place before acting. |
Or skip the browser setup
PyAutoGUI is the right tool when the task is to locate an image in a local file or on your desktop. If your actual task is to capture a web page as an image or PDF, ScreenshotNeo offers a one-request screenshot API; it does not search your desktop or replace local locate calls. Its cookie/consent banners, newsletter popups, and chat widgets are removed before capture; bot checks, blank pages, and failed loads are never billed; and an MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000.
Use the API key from your account. See the ScreenshotNeo API documentation for parameters and response details.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSign up free for 1,000 screenshots a month with no card.
Frequently asked questions
Can locate find an image in a video?
The documented functions search supplied images or the current screen; the documentation cited here does not describe a video-search function. A workflow involving video would need to provide frames as images to search.
Does locate click the match?
No. The locate calls return a box or point. The documented pyautogui.click('image.png') shortcut combines a screen search with a click at the first match’s center.
Can I search only part of an image file?
The documented region option is described for screen-search functions. For a supplied haystack image, the direct documented pattern is to search that image with locate; crop the haystack to the desired area if you need a separately bounded image search.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →
