📝 Configuration Options

Configure venv-selector to match your workflow and preferences. All options are optional.

⚙️ Core Behavior Options

🔧 enable_default_searches

Controls whether the built-in search methods are enabled.

Type: boolean
Default: true

options = {
  enable_default_searches = true
}

What are default searches?

The plugin includes built-in search functions for common Python environment managers like Poetry, Conda, Pipenv, and standard venv/virtualenv setups.

When to disable

Only set to false if you want to use exclusively custom search functions defined in your configuration.

⚡ search_timeout

Maximum time (in seconds) to wait for virtual environment searches to complete.

Type: number
Default: 5

options = {
  search_timeout = 10 -- Wait up to 10 seconds
}

Performance

If you have large directory trees or slow storage, consider increasing this value. For faster systems, you might decrease it.

📁 fd_binary_name

Specify the name of the fd binary to use for file searches.

Type: string | nil
Default: Auto-detected (fd or fdfind)

options = {
  fd_binary_name = "fd" -- or "fdfind" on some systems
}

Auto-detection

The plugin automatically detects whether your system uses fd or fdfind. Only set this if you have a custom installation.

🎯 Environment Activation Options

🐍 activate_venv_in_terminal

Activate the selected Python interpreter in terminal windows opened from Neovim.

Type: boolean
Default: true

options = {
  activate_venv_in_terminal = true
}

Terminal Integration

When enabled, new terminals will automatically have the correct Python environment activated, making it seamless to run Python commands.

🌍 set_environment_variables

Set VIRTUAL_ENV or CONDA_PREFIX environment variables when a virtual environment is activated.

Type: boolean
Default: true

options = {
  set_environment_variables = true
}

Environment Variables

VIRTUAL_ENV: Set for venv/virtualenv environments
CONDA_PREFIX: Set for Conda environments
These variables help other tools detect the active environment

🔒 require_lsp_activation

Require an LSP server to be active before setting environment variables.

Type: boolean
Default: true

options = {
  require_lsp_activation = true
}

Why this exists

This prevents environment variables from being set when no Python LSP is running, which could interfere with other tools.

💾 Caching Options

🗄️ enable_cached_venvs

Use cached virtual environments that are automatically activated when Python files are opened.

Type: boolean
Default: true

options = {
  enable_cached_venvs = true
}

Performance Boost

Caching remembers which virtual environments were used for specific projects, and activates it automatically.

🔄 cached_venv_automatic_activation

Automatically activate cached virtual environments, or require manual activation.

Type: boolean
Default: true

options = {
  cached_venv_automatic_activation = false -- Manual activation
}

Manual Mode

When set to false, use the :VenvSelectCached command to manually activate cached environments.

🔔 User Interface Options

🐛 debug

Enable debug mode to access detailed logging via :VenvSelectLog.

Type: boolean
Default: false

options = {
  debug = true
}

Performance

Only enable during troubleshooting as it adds overhead and verbose logging.

📢 notify_user_on_venv_activation

Show a notification when a virtual environment is activated.

Type: boolean
Default: false

options = {
  notify_user_on_venv_activation = true
}

Visual Feedback

Enable this if you want clear confirmation when virtual environments are switched.

🎨 Picker Configuration

🔭 picker

Choose which picker interface to use for virtual environment selection.

Type: string
Default: "telescope"
Options: "telescope", "fzf-lua", "snacks", "mini-pick", "native"

Telescope
FZF-Lua
Native

options = {
  picker = "telescope"
}

Most feature-rich option with fuzzy finding and preview.

options = {
  picker = "fzf-lua"
}

Fast and lightweight alternative to Telescope.

options = {
  picker = "native"
}

Simple built-in picker, no external dependencies.

🔍 picker_filter_type

How pickers filter results when typing.

Type: string
Default: "substring"
Options: "substring", "character"

options = {
  picker_filter_type = "substring" -- or "character"
}

substring: Match consecutive characters (more intuitive)
character: Match individual characters in order (more flexible)

Universal Setting

This applies to all picker types, not just Telescope.

🎨 selected_venv_marker_color

Color used to highlight the currently active virtual environment marker.

Type: string
Default: "#00FF00"

options = {
  selected_venv_marker_color = "#FF6B35" -- Orange highlight
}

Color Formats

Use hex color codes like #FF0000 for red or #00FF00 for green.

✔️ selected_venv_marker_icon

Icon used to mark the currently selected virtual environment in the picker.

Type: string
Default: "✔"

options = {
  selected_venv_marker_icon = "🐍" -- Custom marker icon
}

Visual Indicator

This icon appears next to the currently active environment in picker results.

🎯 picker_icons

Override default icons for different virtual environment types in the picker.

Type: table
Default: {}

options = {
  picker_icons = {
    poetry = "📝",
    hatch = "🥚", 
    conda = "🐍",
    default = "🐍"
  }
}

Icon Customization

Define custom icons for specific environment types. The default key sets the fallback icon for unspecified types.

📊 picker_columns

Configure which columns to display and their order in picker results.

Type: table
Default: { "marker", "search_icon", "search_name", "search_result" }

options = {
  picker_columns = { "marker", "search_name", "search_result" } -- Hide search_icon
}

Available Columns:

marker: Shows selected environment indicator
search_icon: Icon for the search type
search_name: Name of the search method
search_result: The actual environment path/name

Column Control

Omit columns from the array to hide them completely from the picker interface.

🪝 Callback Functions

🎯 on_venv_activate_callback

Function called after a virtual environment is successfully activated.

Type: function | nil
Default: nil

options = {
  on_venv_activate_callback = function(venv_path, venv_python)
    -- venv_path: path to the virtual environment root
    -- venv_python: path to the Python executable
    print("Switched to: " .. venv_path)
    
    -- Example: Update statusline
    vim.g.current_venv = vim.fn.fnamemodify(venv_path, ":t")
  end
}

Parameters:

venv_path (string): Absolute path to virtual environment root
venv_python (string): Absolute path to Python executable

Use Cases

Update statusline or UI components
Configure other plugins for the new environment
Log environment changes
Send notifications to external tools

More details in the callbacks section.

🔧 on_fd_result_callback

Function to modify or filter search results before they're displayed.

Type: function | nil
Default: nil

options = {
  on_fd_result_callback = function(fd_results)
    -- fd_results: table of file paths found by fd
    -- Return modified table
    
    -- Example: Filter out test environments
    local filtered = {}
    for _, path in ipairs(fd_results) do
      if not path:match("test") then
        table.insert(filtered, path)
      end
    end
    return filtered
  end
}

Parameters:

fd_results (table): Array of file paths found by fd

Returns: Modified table of paths

More details in the callbacks section.

🔭 on_telescope_result_callback

Function to modify Telescope picker results before they're displayed.

Type: function | nil
Default: nil

options = {
  on_telescope_result_callback = function(results)
    -- results: table of telescope entries
    -- Return modified table
    
    -- Example: Add custom formatting to results
    for _, result in ipairs(results) do
      result.display = "Custom: " .. result.display
    end
    return results
  end
}

Parameters:

results (table): Array of Telescope result entries

Returns: Modified table of results

Telescope Only

This callback only applies when using the Telescope picker.

📊 Statusline Integration

📈 statusline_func

Functions to customize the output for statusline integrations with Lualine and NvChad.

Type: table | nil
Default: nil

options = {
  statusline_func = {
    lualine = function()
      local venv_path = require("venv-selector").venv()
      if not venv_path or venv_path == "" then
        return ""
      end
      
      local venv_name = vim.fn.fnamemodify(venv_path, ":t")
      if not venv_name then
        return ""
      end
      
      local output = "🐍 " .. venv_name .. " "
      return output
    end,
    nvchad = function()
      local venv_path = require("venv-selector").venv()
      if not venv_path or venv_path == "" then
        return ""
      end
      
      local venv_name = vim.fn.fnamemodify(venv_path, ":t")
      if not venv_name then
        return ""
      end
      
      local output = "🐍 " .. venv_name .. " "
      return output
    end,
  }
}

Lualine Integration

To integrate with Lualine, add "venv-selector" to your statusline configuration:

{
  "nvim-lualine/lualine.nvim",
  event = "VeryLazy",
  config = function()
    require("lualine").setup {
      sections = {
        lualine_a = { "mode" },
        lualine_b = { "branch", "diff", "diagnostics" },
        lualine_c = { "filename" },
        lualine_x = {
          "venv-selector", -- Add this line
          "encoding",
          "fileformat",
          "filetype",
        },
        lualine_y = { "progress" },
        lualine_z = { "location" },
      },
    }
  end,
  dependencies = { "nvim-tree/nvim-web-devicons" },
}

NvChad Integration

Edit your ~/.config/nvim/lua/chadrc.lua file:

M.ui = {
  statusline = {
    modules = {
      venv = require("venv-selector.statusline.nvchad").render
    },
    order = { "mode", "file", "git", "%=", "lsp_msg", "diagnostics", "venv", "lsp", "cwd" }
  }
}

Customization

Both functions receive no parameters and should return a string to display in the statusline. Return an empty string "" to hide the statusline component.

📋 Configuration Example

require("venv-selector").setup({
  search = {}, -- your own searches are configured in here
  options = {
    -- Core behavior
    enable_default_searches = true,
    search_timeout = 5,
    fd_binary_name = "fd", -- or "fdfind"
    
    -- Environment activation
    activate_venv_in_terminal = true,
    set_environment_variables = true,
    require_lsp_activation = true,
    
    -- Caching
    enable_cached_venvs = true,
    cached_venv_automatic_activation = true,
    
    -- User interface
    notify_user_on_venv_activation = true,
    debug = false,
    
    -- Picker configuration
    picker = "telescope",
    picker_filter_type = "substring",
    selected_venv_marker_color = "#00FF00",
    selected_venv_marker_icon = "✔",
    picker_icons = {
      poetry = "📝",
      hatch = "🥚",
      conda = "🐍",
      default = "🐍"
    },
    picker_columns = { "marker", "search_icon", "search_name", "search_result" },
    
    -- Callbacks
    on_venv_activate_callback = function(venv_path, venv_python)
        -- Custom logic after activation
        print("Activated: " .. vim.fn.fnamemodify(venv_path, ":t"))
    end,
    
    on_fd_result_callback = function(fd_results)
        -- Filter out test environments
        local filtered = {}
        for _, path in ipairs(fd_results) do
          if not path:match("test") then
            table.insert(filtered, path)
          end
        end
        return filtered
    end,
    
    on_telescope_result_callback = function(results)
        -- Custom telescope result formatting
        for _, result in ipairs(results) do
          result.display = "🚀 " .. result.display
        end
        return results
    end,
    
    -- Statusline integration
    statusline_func = {
      lualine = function()
        local venv_path = require("venv-selector").venv()
        if not venv_path or venv_path == "" then
          return ""
        end
        local venv_name = vim.fn.fnamemodify(venv_path, ":t")
        return "🐍 " .. (venv_name or "") .. " "
      end,
      nvchad = function()
        local venv_path = require("venv-selector").venv()
        if not venv_path or venv_path == "" then
          return ""
        end
        local venv_name = vim.fn.fnamemodify(venv_path, ":t")
        return "🐍 " .. (venv_name or "") .. " "
      end,
    },
  }
})

Getting Started

Start with the minimal setup and gradually add options as needed.

⚙️ Core Behavior Options​

🎯 Environment Activation Options​

💾 Caching Options​

🔔 User Interface Options​

🎨 Picker Configuration​

🪝 Callback Functions​

📊 Statusline Integration​

Lualine Integration​

NvChad Integration​

📋 Configuration Example​

⚙️ Core Behavior Options

🎯 Environment Activation Options

💾 Caching Options

🔔 User Interface Options

🎨 Picker Configuration

🪝 Callback Functions

📊 Statusline Integration

Lualine Integration

NvChad Integration

📋 Configuration Example