{"id":13496181,"url":"https://github.com/mfussenegger/nvim-dap-python","last_synced_at":"2025-05-15T09:00:23.157Z","repository":{"id":37746205,"uuid":"313014506","full_name":"mfussenegger/nvim-dap-python","owner":"mfussenegger","description":"An extension for nvim-dap, providing default configurations for python and methods to debug individual test methods or classes.","archived":false,"fork":false,"pushed_at":"2025-05-12T19:18:13.000Z","size":73,"stargazers_count":648,"open_issues_count":3,"forks_count":52,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-12T20:34:43.052Z","etag":null,"topics":["debug-adapter-protocol","debugger","debugging","neovim","neovim-plugin","nvim-dap"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mfussenegger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["mfussenegger"]}},"created_at":"2020-11-15T11:18:37.000Z","updated_at":"2025-05-12T19:18:16.000Z","dependencies_parsed_at":"2024-06-03T20:57:13.752Z","dependency_job_id":"29482b28-2e60-4059-8fd8-613f653ab9a5","html_url":"https://github.com/mfussenegger/nvim-dap-python","commit_stats":{"total_commits":67,"total_committers":20,"mean_commits":3.35,"dds":"0.31343283582089554","last_synced_commit":"3e3dd98d4d83715c9e0e429b4a5da7bd706e6ceb"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfussenegger%2Fnvim-dap-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfussenegger%2Fnvim-dap-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfussenegger%2Fnvim-dap-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfussenegger%2Fnvim-dap-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mfussenegger","download_url":"https://codeload.github.com/mfussenegger/nvim-dap-python/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254310509,"owners_count":22049467,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debug-adapter-protocol","debugger","debugging","neovim","neovim-plugin","nvim-dap"],"created_at":"2024-07-31T19:01:43.469Z","updated_at":"2025-05-15T09:00:23.135Z","avatar_url":"https://github.com/mfussenegger.png","language":"Lua","funding_links":["https://github.com/sponsors/mfussenegger"],"categories":["Lua"],"sub_categories":[],"readme":"# nvim-dap-python\n\nAn extension for [nvim-dap][1] providing default configurations for python and methods to debug individual test methods or classes.\n\n\n## Installation\n\n- Requires Neovim \u003e= 0.5\n- Requires [nvim-dap][1]\n- Requires [debugpy][3]\n- Install like any other neovim plugin:\n  - If using [vim-plug][6]: `Plug 'mfussenegger/nvim-dap-python'`\n  - If using [packer.nvim][7]: `use 'mfussenegger/nvim-dap-python'`\n\nIf you want to use the test runner functionality, it additionally requires a\ntree sitter parser for Python.\n\n\n### Debugpy\n\nOptions to install [debugpy][3]:\n\n1. Via a system package manager. For example:\n\n```bash\npacman -S python-debugpy\n```\n\n2. Via `pip` in a `venv`:\n\n```bash\nmkdir ~/.virtualenvs\ncd ~/.virtualenvs\npython -m venv debugpy\ndebugpy/bin/python -m pip install debugpy\n```\n\nNote that the virutalenv used for the `debugpy` can be independent from any\nvirtualenv you're using in your projects.\n\n`nvim-dap-python` tries to detect your project `venv` and should recognize any\ndependencies your project has. See [Python dependencies and\nvirtualenv](#python-dependencies-and-virtualenv)\n\n\n3. Implicit via [uv][uv]\n\nSee [Usage](#usage): You need to use `require(\"dap-python\").setup(\"uv\")`\n\n\n### Tree-sitter\n\nTo install the python tree-sitter parser you can either:\n\n- Use `:TSInstall python` from [nvim-treesitter][4]\n- Compile the parser from [tree-sitter-python][5] and copy it into `.config/nvim/parser/`:\n  - `git clone https://github.com/tree-sitter/tree-sitter-python.git`\n  - `cd tree-sitter-python`\n  - `cc -O2 -o ~/.config/nvim/parser/python}.so -I./src src/parser.c src/scanner.cc -shared -Os -lstdc++ -fPIC`\n\n\n## Usage\n\n1. Call `setup` in your `init.lua` to register the adapter and configurations.\n\n   If installed in a virtual environment:\n\n   ```lua\n   require(\"dap-python\").setup(\"/path/to/venv/bin/python\")\n   -- If using the above, then `/path/to/venv/bin/python -m debugpy --version`\n   -- must work in the shell\n   ```\n\n   If installed globally:\n\n   ```lua\n   require(\"dap-python\").setup(\"python3\")\n   -- If using the above, then `python3 -m debugpy --version`\n   -- must work in the shell\n   ```\n\n   Newer versions of `debugpy` also include a `debugpy-adapter` executable\n   which you can use in place of the `python` executable.\n\n\n   If using [uv][uv]:\n\n   ```lua\n   require(\"dap-python\").setup(\"uv\")\n   ```\n\n\n2. Use `nvim-dap` as usual.\n\n   - Call `:lua require('dap').continue()` to start debugging.\n   - See `:help dap-mappings` and `:help dap-api`.\n   - Use `:lua require('dap-python').test_method()` to debug the closest method above the cursor.\n\n   Supported test frameworks are `unittest`, `pytest` and `django`. By default it\n   tries to detect the runner by probing for presence of `pytest.ini` or\n   `manage.py`, or for a `tool.pytest` directive inside `pyproject.toml`, if\n   none are present it defaults to `unittest`.\n\n   To configure a different runner, change the `test_runner` variable. For\n   example, to configure `pytest` set the test runner like this in your\n   `init.lua`:\n\n   ```lua\n   require('dap-python').test_runner = 'pytest'\n   ```\n\n   You can also add custom runners. An example in `Lua`:\n\n   ```lua\n   local test_runners = require('dap-python').test_runners\n\n   -- `test_runners` is a table. The keys are the runner names like `unittest` or `pytest`.\n   -- The value is a function that takes two arguments:\n   -- The classnames and a methodname\n   -- The function must return a module name and the arguments passed to the module as list.\n\n   ---@param classnames string[]\n   ---@param methodname string?\n   test_runners.your_runner = function(classnames, methodname)\n     local path = table.concat({\n        table.concat(classnames, \":\"),\n        methodname,\n     }, \"::\")\n     return 'modulename', {\"-s\", path}\n   end\n   ```\n\n\n### Documentation\n\nSee `:help dap-python`\n\n\n## Mappings\n\n\n```vimL\nnnoremap \u003csilent\u003e \u003cleader\u003edn :lua require('dap-python').test_method()\u003cCR\u003e\nnnoremap \u003csilent\u003e \u003cleader\u003edf :lua require('dap-python').test_class()\u003cCR\u003e\nvnoremap \u003csilent\u003e \u003cleader\u003eds \u003cESC\u003e:lua require('dap-python').debug_selection()\u003cCR\u003e\n```\n\n\n## Custom configuration\n\nIf you call the `require('dap-python').setup` method it will create a few\n`nvim-dap` configuration entries. These configurations are general purpose\nconfigurations suitable for many use cases, but you may need to customize the\nconfigurations - for example if you want to use Docker containers.\n\nTo add your own entries you can create per project `.vscode/launch.json`\nconfiguration files. See `:help dap-launch.json`.\n\nOr you can add your own global entries by extending the\n`dap.configurations.python` list after calling the `setup` function:\n\n```lua\nrequire('dap-python').setup('/path/to/python')\ntable.insert(require('dap').configurations.python, {\n  type = 'python',\n  request = 'launch',\n  name = 'My custom launch configuration',\n  program = '${file}',\n  -- ... more options, see https://github.com/microsoft/debugpy/wiki/Debug-configuration-settings\n})\n```\n\nThe [Debugpy Wiki][debugpy_wiki] contains a list of all supported configuration options.\n\n\n## Python dependencies and virtualenv\n\n`nvim-dap-python` by default tries to detect a virtual environment and uses it\nwhen debugging your application. It looks for:\n\n- The environment variables `VIRTUAL_ENV` and `CONDA_PREFIX`\n- The folders `venv`, `.venv`, `env`, `.env` relative to either the current\n  working directory or the `root_dir` of a active language server client. See\n  `:h lsp.txt` for more information about the latter.\n\nIf you're using another way to manage virtual environments, you can set a\ncustom `resolve_python` function:\n\n```lua\nrequire('dap-python').resolve_python = function()\n  return '/absolute/path/to/python'\nend\n```\n\nOr explicitly set the `pythonPath` property within your debugpy/nvim-dap\nconfigurations. See `:h dap-configuration` and [Launch/Attach\nSettings][debugpy_wiki]\n\n\n## Alternatives\n\n### [vim-ultest](https://github.com/rcarriga/vim-ultest)\n\nA test runner building upon vim-test with nvim-dap support.\nAims to work for all python runners.\n\n## Development\n\n- Generate docs using [vimcats][vimcats]:\n\n```bash\nvimcats -f -t lua/dap-python.lua \u003e doc/dap-python.txt\n```\n\n\n[1]: https://github.com/mfussenegger/nvim-dap\n[3]: https://github.com/microsoft/debugpy\n[4]: https://github.com/nvim-treesitter/nvim-treesitter\n[5]: https://github.com/tree-sitter/tree-sitter-python\n[6]: https://github.com/junegunn/vim-plug\n[7]: https://github.com/wbthomason/packer.nvim\n[debugpy_wiki]: https://github.com/microsoft/debugpy/wiki/Debug-configuration-settings\n[vimcats]: https://github.com/mrcjkb/vimcats\n[uv]: https://docs.astral.sh/uv/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfussenegger%2Fnvim-dap-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmfussenegger%2Fnvim-dap-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfussenegger%2Fnvim-dap-python/lists"}