Home

1. Requirements

Below is a list of all dependencies. However, you don't have to install all of them in this step.

Neovim environment

• Neovim 0.9.5+
• telescope.nvim, fzf-lua, or snacks.nvim to present pickers.
• nui.nvim to present floating code coverage report.
• snacks.nvim to show previews for SwiftUI, UIKit, and AppKit views.
• nvim-tree, neo-tree, or oil.nvim to visually manage your project files.
• nvim-dap and nvim-dap-ui to debug apps.
• nvim-treesitter + Swift parser to show test results for tests written using Quick framework.

External tools

• xcbeautify to format Xcode logs (you can set a different tool or disable formatting in the config).
• XcodeProjectCLI to manage project files within Neovim.
• pymobiledevice3 to debug on physical devices and/or run apps on devices below iOS 17.
• jq to extract some information from pymobiledevice3.
• xcode-build-server to make LSP work properly with xcodeproj/xcworkspace.
• ripgrep to find matching test files when using Swift Testing framework.
• coreutils to print macOS app logs without attaching debugger.
• Xcode to build, run, and test apps. Make sure that xcodebuild and xcrun simctl work correctly. Tested with Xcode 15+.

 

2. Install plugin

💤 lazy.nvim

return {
  "wojciech-kulik/xcodebuild.nvim",
  dependencies = {
    -- Uncomment a picker that you want to use, snacks.nvim might be additionally 
    -- useful to show previews and failing snapshots.

    -- You must select at least one:
    -- "nvim-telescope/telescope.nvim",
    -- "ibhagwan/fzf-lua",
    -- "folke/snacks.nvim", -- (optional) to show previews

    "MunifTanjim/nui.nvim",
    "nvim-tree/nvim-tree.lua", -- (optional) to manage project files
    "stevearc/oil.nvim", -- (optional) to manage project files
    "nvim-treesitter/nvim-treesitter", -- (optional) for Quick tests support (required Swift parser)
  },
  config = function()
    require("xcodebuild").setup({
        -- put some options here or leave it empty to use default settings
    })
  end,
}

Below setup you can add some bindings. Check out suggested key bindings.

 

3. Install external tools

brew install xcode-build-server xcbeautify pipx rg jq coreutils
brew install wojciech-kulik/tap/xcp
pipx install pymobiledevice3

To quickly install all required tools you can run:

cd ~/.local/share/nvim/lazy/xcodebuild.nvim
make install

 

4. Setup Neovim for iOS development

Follow the guide: Neovim Configuration.

 

5. Configure integrations

Check out available integrations and pick which one you want to use.

 

6. Improve build time

If you use Xcode version below 26, you can apply this workaround to improve build time.

 

7. Usage

Make sure to start Neovim in your project's root directory and run XcodebuildSetup to configure it. The plugin needs several information like project file, scheme, config, device, and test plan to run commands.

If the list of devices is empty, please check out the issue #285.

Once the project is configured you can run :XcodebuildPicker to see all available actions.

Remember, that all the information are available in the help :h xcodebuild. Every function is documented and described both in the help and in the code.

API: If you want to use functions directly instead of user commands, then please see xcodebuild.actions module.

 

Useful Help Tags

• :h xcodebuild
• :h xcodebuild.config
• :h xcodebuild.keys
• :h xcodebuild.tools
• :h xcodebuild.commands
• :h xcodebuild.events
• :h xcodebuild.highlights
• :h xcodebuild.dap