Skip to main content

​
Buffer API Functions

Buffer functions operate on Neovim buffers. They are prefixed with nvim_buf_*.

​
Buffer Information

​
nvim_buf_line_count()

Returns the number of lines in the given buffer.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
return
integer
Line count, or 0 for unloaded buffer
local count = vim.api.nvim_buf_line_count(0)
print('Line count: ' .. count)

​
nvim_buf_is_loaded()

Checks if a buffer is valid and loaded.
​
buffer
integer
required
Buffer handle
​
return
boolean
true if the buffer is valid and loaded

​
nvim_buf_is_valid()

Checks if a buffer is valid.
​
buffer
integer
required
Buffer handle
​
return
boolean
true if the buffer is valid

​
nvim_buf_get_name()

Gets the full file name for the buffer.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
return
string
Buffer name (full path)

​
nvim_buf_set_name()

Sets the full file name for a buffer.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
name
string
required
Buffer name

​
Line Operations

​
nvim_buf_get_lines()

Gets a line-range from the buffer. Indexing is zero-based, end-exclusive.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
start
integer
required
First line index
​
end
integer
required
Last line index (exclusive)
​
strict_indexing
boolean
required
Whether out-of-bounds should be an error
​
return
string[]
Array of lines
-- Get all lines in buffer
local lines = vim.api.nvim_buf_get_lines(0, 0, -1, false)

-- Get lines 5-10
local subset = vim.api.nvim_buf_get_lines(0, 5, 10, false)

-- Get last line
local last_line = vim.api.nvim_buf_get_lines(0, -2, -1, false)

​
nvim_buf_set_lines()

Sets (replaces) a line-range in the buffer. Indexing is zero-based, end-exclusive.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
start
integer
required
First line index
​
end
integer
required
Last line index (exclusive)
​
strict_indexing
boolean
required
Whether out-of-bounds should be an error
​
replacement
string[]
required
Array of lines to use as replacement
-- Replace lines 0-2 with new content
vim.api.nvim_buf_set_lines(0, 0, 2, false, {'line 1', 'line 2'})

-- Insert lines at position 5
vim.api.nvim_buf_set_lines(0, 5, 5, false, {'new line'})

-- Delete lines 10-15
vim.api.nvim_buf_set_lines(0, 10, 15, false, {})

-- Append to end of buffer
vim.api.nvim_buf_set_lines(0, -1, -1, false, {'appended line'})

​
nvim_buf_get_text()

Gets a range from the buffer (may be partial lines). Indexing is zero-based, row indices are end-inclusive, column indices are end-exclusive.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
start_row
integer
required
First line index
​
start_col
integer
required
Starting column (byte offset) on first line
​
end_row
integer
required
Last line index (inclusive)
​
end_col
integer
required
Ending column (byte offset) on last line (exclusive)
​
opts
table
required
Optional parameters (reserved)
​
return
string[]
Array of lines
-- Get text from line 0, col 5 to line 0, col 10
local text = vim.api.nvim_buf_get_text(0, 0, 5, 0, 10, {})

-- Get text spanning multiple lines
local multiline = vim.api.nvim_buf_get_text(0, 0, 0, 2, 10, {})

​
nvim_buf_set_text()

Sets (replaces) a range in the buffer. This is recommended over nvim_buf_set_lines() when only modifying parts of a line, as extmarks will be preserved.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
start_row
integer
required
First line index
​
start_col
integer
required
Starting column (byte offset) on first line
​
end_row
integer
required
Last line index (inclusive)
​
end_col
integer
required
Ending column (byte offset) on last line (exclusive)
​
replacement
string[]
required
Array of lines to use as replacement
-- Replace text on line 0 from col 5 to 10
vim.api.nvim_buf_set_text(0, 0, 5, 0, 10, {'hello'})

-- Insert text at a position
vim.api.nvim_buf_set_text(0, 0, 5, 0, 5, {'inserted '})

-- Delete text
vim.api.nvim_buf_set_text(0, 0, 5, 0, 10, {})

​
Buffer Variables

​
nvim_buf_get_var()

Gets a buffer-scoped (b:) variable.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
name
string
required
Variable name
​
return
any
Variable value

​
nvim_buf_set_var()

Sets a buffer-scoped (b:) variable.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
name
string
required
Variable name
​
value
any
required
Variable value

​
nvim_buf_del_var()

Removes a buffer-scoped (b:) variable.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
name
string
required
Variable name

​
Buffer Marks

​
nvim_buf_get_mark()

Returns a (row, col) tuple representing the position of the named mark. Marks are (1,0)-indexed.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
name
string
required
Mark name (must be a single char)
​
return
integer[]
(row, col) tuple, (0, 0) if the mark is not set
local mark = vim.api.nvim_buf_get_mark(0, 'a')
print('Mark a is at row ' .. mark[1] .. ', col ' .. mark[2])

​
nvim_buf_set_mark()

Sets a named mark in the given buffer. Marks are (1,0)-indexed.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
name
string
required
Mark name (must be a single char)
​
line
integer
required
Line number (1-indexed)
​
col
integer
required
Column number (0-indexed)
​
opts
table
required
Optional parameters (reserved)
​
return
boolean
true if the mark was set

​
nvim_buf_del_mark()

Deletes a named mark in the buffer.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
name
string
required
Mark name (must be a single char)
​
return
boolean
true if the mark was deleted

​
Buffer Metadata

​
nvim_buf_get_changedtick()

Gets a changed tick of a buffer (b:changedtick).
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
return
integer
b:changedtick value

​
nvim_buf_get_offset()

Returns the byte offset of a line (0-indexed).
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
index
integer
required
Line index
​
return
integer
Integer byte offset, or -1 for unloaded buffer

​
Buffer Management

​
nvim_buf_delete()

Deletes a buffer and its metadata (like :bwipeout).
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
opts
table
required
Optional parameters:
  • force: Force deletion, ignore unsaved changes
  • unload: Unload only (:bunload), do not delete
-- Delete buffer forcefully
vim.api.nvim_buf_delete(bufnr, { force = true })

-- Unload buffer
vim.api.nvim_buf_delete(bufnr, { unload = true })

​
nvim_buf_call()

Calls a function with buffer as temporary current buffer.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
fun
function
required
Function to call inside the buffer (Lua only)
​
return
any
Return value of function
local result = vim.api.nvim_buf_call(bufnr, function()
  -- Operations here use bufnr as current buffer
  return vim.fn.line('$')
end)

​
Buffer Updates

​
nvim_buf_attach()

Activates buffer update events on a channel, or as Lua callbacks.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
send_buffer
boolean
required
True if the initial notification should contain the whole buffer
​
opts
table
required
Optional parameters:
  • on_lines: Callback for line changes
  • on_bytes: Callback for byte changes
  • on_changedtick: Callback for changedtick updates
  • on_detach: Callback for detach
  • on_reload: Callback for buffer reload
  • utf_sizes: Include UTF-32 and UTF-16 sizes
  • preview: Also attach to command preview
​
return
boolean
False if attach failed; otherwise true
local events = {}
vim.api.nvim_buf_attach(0, false, {
  on_lines = function(_, bufnr, changedtick, firstline, lastline, new_lastline)
    table.insert(events, {
      bufnr = bufnr,
      firstline = firstline,
      lastline = lastline
    })
  end
})

​
nvim_buf_detach()

Deactivates buffer-update events on the channel.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
return
boolean
False if detach failed; otherwise true

​
Buffer Keymaps

​
nvim_buf_get_keymap()

Gets a list of buffer-local mapping definitions.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
mode
string
required
Mode short-name (“n”, “i”, “v”, …)
​
return
table[]
Array of maparg()-like dictionaries

​
nvim_buf_set_keymap()

Sets a buffer-local mapping for the given mode.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
mode
string
required
Mode short-name
​
lhs
string
required
Left-hand-side of the mapping
​
rhs
string
required
Right-hand-side of the mapping
​
opts
table
required
Optional parameters (noremap, silent, expr, etc.)

​
nvim_buf_del_keymap()

Unmaps a buffer-local mapping for the given mode.
​
buffer
integer
required
Buffer handle, or 0 for current buffer
​
mode
string
required
Mode short-name
​
lhs
string
required
Left-hand-side of the mapping

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us