{"record":{"id":"2345949904279235","repo":"matplotlib/matplotlib","slug":"subplot-got-an-unexpected-keyword-argument-ncol","errorCode":null,"errorMessage":"subplot() got an unexpected keyword argument 'ncols' and/or 'nrows'.  Did you intend to call subplots()?","messagePattern":"subplot\\(\\) got an unexpected keyword argument 'ncols' and/or 'nrows'\\.  Did you intend to call subplots\\(\\)\\?","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"lib/matplotlib/pyplot.py","lineNumber":1653,"sourceCode":"            )\n        kwargs['projection'] = projection = 'polar'\n\n    # if subplot called without arguments, create subplot(1, 1, 1)\n    if len(args) == 0:\n        args = (1, 1, 1)\n\n    # This check was added because it is very easy to type subplot(1, 2, False)\n    # when subplots(1, 2, False) was intended (sharex=False, that is). In most\n    # cases, no error will ever occur, but mysterious behavior can result\n    # because what was intended to be the sharex argument is instead treated as\n    # a subplot index for subplot()\n    if len(args) >= 3 and isinstance(args[2], bool):\n        _api.warn_external(\"The subplot index argument to subplot() appears \"\n                           \"to be a boolean. Did you intend to use \"\n                           \"subplots()?\")\n    # Check for nrows and ncols, which are not valid subplot args:\n    if 'nrows' in kwargs or 'ncols' in kwargs:\n        raise TypeError(\"subplot() got an unexpected keyword argument 'ncols' \"\n                        \"and/or 'nrows'.  Did you intend to call subplots()?\")\n\n    fig = gcf()\n\n    # First, search for an existing subplot with a matching spec.\n    key = SubplotSpec._from_subplot_args(fig, args)\n\n    for ax in fig.axes:\n        # If we found an Axes at the position, we can reuse it if the user passed no\n        # kwargs or if the Axes class and kwargs are identical.\n        if (ax.get_subplotspec() == key\n            and (kwargs == {}\n                 or (ax._projection_init\n                     == fig._process_projection_requirements(**kwargs)))):\n            break\n    else:\n        # we have exhausted the known Axes and none match, make a new one!\n        ax = fig.add_subplot(*args, **kwargs)","sourceCodeStart":1635,"sourceCodeEnd":1671,"githubUrl":"https://github.com/matplotlib/matplotlib/blob/b379c1b69e012b142c0f496a52bcb30513802d72/lib/matplotlib/pyplot.py#L1635-L1671","documentation":"plt.subplot() (singular) places ONE axes in a figure using positional integers (nrows, ncols, index); it does not accept nrows/ncols as keywords. Passing either raises TypeError('subplot() got an unexpected keyword argument ... Did you intend to call subplots()?') - a deliberate typo-trap for the very common slip of calling subplot() when a whole grid via plt.subplots(nrows=..., ncols=...) was meant. The related bool-as-index case only warns, but nrows/ncols hard-errors.","triggerScenarios":"plt.subplot(nrows=2, ncols=2); plt.subplot(2, 2, 1, ncols=2); refactoring plt.subplots(2, 2) into per-panel calls and keeping the keyword style; autocomplete choosing subplot over subplots.","commonSituations":"The singular/plural API pair is matplotlib's most common name confusion; IDE autocompletion picking the shorter name; code converted from object API (fig.subplots) back to pyplot.","solutions":["If you want the whole grid at once, call plt.subplots(2, 2) (returns fig, ax array)","If you want one panel, pass the spec positionally: plt.subplot(2, 2, 1)","Search the codebase for 'subplot(nrows' / 'subplot(ncols' - every hit is this bug"],"exampleFix":"# before\nfig, ax = plt.subplot(nrows=2, ncols=2)  # TypeError: did you mean subplots()?\n\n# after\nfig, axs = plt.subplots(nrows=2, ncols=2)","handlingStrategy":"validation","validationCode":"def subplot_or_subplots(**kw):\n    if {'nrows', 'ncols'} & set(kw):\n        raise TypeError('nrows/ncols belong to plt.subplots(); use it instead')\n    return plt.subplot(**kw)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["plt.subplot (one panel, positional ints) vs plt.subplots (whole grid, keywords) - memorize the pair","Never pass nrows/ncols as keywords to subplot(); the spec is positional (nrows, ncols, index)","Code-review grep for 'subplot(nrows' and 'subplot(ncols' catches every instance of this slip"],"tags":["matplotlib","pyplot","subplot","subplots","api-confusion","typeerror"],"backgroundTag":"similar-api-name-confusion","analyzedSha":"b379c1b69e012b142c0f496a52bcb30513802d72","analyzedAt":"2026-08-21T23:31:55.468Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}