pipenv.nvim

Asynchronous management for your Pipenv environment from within Neovim.

https://github.com/user-attachments/assets/170e9897-c501-4a33-b96a-3e266d79045d

Table Of Contents

• Installation
• Configuration
  • Pipenv Environment Variables
• Usage
  • No Subcommands
  • Subcommands
  • picker.nvim Integration
• API
• License

Installation

Requirements

• Neovim >=v0.9.0
• Pipenv
• wsdjeg/job.nvim
• xieyonn/spinner.nvim - (OPTIONAL, RECOMMENDED)
• wsdjeg/picker.nvim - (OPTIONAL)

{
  'DrKJeff16/pipenv.nvim',
  dependencies = {
    'wsdjeg/job.nvim', -- REQUIRED!
    'xieyonn/spinner.nvim', -- RECOMMENDED
    'wsdjeg/picker.nvim', -- OPTIONAL
  },
  opts = {},
}

require('plug').add({
  {
    'DrKJeff16/pipenv.nvim',
    depends = {
      { 'wsdjeg/job.nvim' }, -- REQUIRED!
      { 'xieyonn/spinner.nvim' }, -- RECOMMENDED
      { 'wsdjeg/picker.nvim' }, -- OPTIONAL
    },
    config = function()
      require('pipenv').setup()
    end,
  }
})

require('pckr').add({
  {
    'DrKJeff16/pipenv.nvim',
    requires = {
      'wsdjeg/job.nvim', -- REQUIRED!
      'xieyonn/spinner.nvim', -- RECOMMENDED
      'wsdjeg/picker.nvim', -- OPTIONAL
    },
    config = function()
      require('pipenv').setup()
    end,
  },
})

local paq = require('paq')
paq({
  'DrKJeff16/pipenv.nvim',
  'wsdjeg/job.nvim', -- REQUIRED!
  'xieyonn/spinner.nvim', -- RECOMMENDED
  'wsdjeg/picker.nvim', -- OPTIONAL
})

luarocks install pipenv.nvim         # Global Install
luarocks install --local pipenv.nvim # Local Install

Configuration

These are the default options:

require('pipenv').setup({
  -- Output window options (`:Pipenv!`)
  output = {
    float = true, -- Set to `false` if you don't want a floating window
    split = 'right', -- right|left|above|below (only matters if `float` is `false`)
    border = 'single', -- none|single|double|rounded|solid|shadow (only matters if `float` is `true`)
    height = 0.85, -- A number between `0` and `1` (percentage) or a fixed height (only matters if `float` is `true`)
    width = 0.85, -- A number between `0` and `1` (percentage) or a fixed width (only matters if `float` is `true`)
    zindex = 100, -- The `zindex` value of the output window (only matters if `float` is `true`)
  },
  env = { -- See the `Pipenv Environment Variables` section
    -- install = {},
    -- virtual_env = {},
    -- file_location = {},
    -- security = {},
    -- behavior = {},
  },
  spinner = {
    enabled = false,
    -- See https://github.com/xieyonn/spinner.nvim for more info about these options
    opts = {
      hl_group = 'Special',
      kind = 'cursor',
      pattern = 'dots13',
      zindex = 100,
      -- attach = {},
      -- col = 0,
      -- fmt = function(event) return '' end,
      -- initial_delay_ms = 10,
      -- ns = 0,
      -- on_update_ui = function(event) end,
      -- placeholder = false,
      -- row = 0,
      -- ttl_ms = 100,
      -- ui_scope = 'Foo',
      -- winblend = 10,
    },
  },
})

Pipenv Environment Variables

You can customize the environment variables used when executing Pipenv operations. By default no option is set as to not interfere with your environment variables, but you may modify any listed in the table below.

For more information consult the Pipenv Documentation.

Example:

-- ARBITRARY EXAMPLE. DO NOT COPY AS-IS!
require('pipenv').setup({
  env = {
    behavior = {
      auto_accept = true,
      ignore_pipfile = true,
    },
    file_location = {
      cache_dir = vim.fn.expand('~/.local/state/pipenv/cache'),
    },
    install = {
      install_dependencies = false,
      resolve_vcs = true,
    },
    security = {
      pyup_api_key = '<API_KEY>',
    },
    virtual_env = {
      venv_name = 'my_venv',
      venv_path = vim.fn.expand('~/.cache/my-virtualenv'),
    },
  },
})

Usage

You can use the :Pipenv command to do certain operations with Pipenv from within Neovim.

To enable verbose mode in any operation simply add a ! to the command (:Pipenv!).

You can also pass these flags:

• dev=true|false - The command is called with a --dev flag.
• pre=true|false - The command is called with a --pre flag.
• file=/path/to/file - The command output will be written to the target file.
• python=PYTHON_VERSION - The python version for Pipenv to use. Must be formatted correctly (e.g. python=3.10, python=3.13, ...).

Keep in mind that any flag that doesn't get parsed by a subcommand can still be passed, only it won't make a difference!

The valid subcommands are:

• clean
• edit
• graph
• help
• install
• list-installed
• list-scripts
• lock
• remove (calling :Pipenv! remove will force its execution instead of enabling verbose mode)
• requirements
• run
• scripts
• sync
• uninstall
• update
• upgrade
• verify

No Subcommands

You can run :Pipenv[!] without any of the subcommands listed above. This will open a UI prompting to do any of the valid Pipenv operations.

Keep in mind flags can still be passed to achieve the same effect for any operation that requires it.

Examples:

:Pipenv                              " verbose=false, dev=false, pre=false, file=nil, python=nil
:Pipenv python=3.10                  " verbose=false, dev=false, pre=false, file=nil, python=3.10
:Pipenv!                             " verbose=true, dev=false, pre=false, file=nil, python=nil
:Pipenv! dev=true file=/path/to/file " verbose=true, dev=true, pre=false, file=/path/to/file, python=nil
:Pipenv dev=true pre=false           " verbose=false, dev=true, pre=true, file=nil, python=nil

Subcommands

Below is a table specifying each subcommand, how many arguments does it take, what flags are valid for parsing and its description.

Examples:

:Pipenv run <COMMANDS>                            " verbose=false
:Pipenv! run <COMMANDS>                           " verbose=true

:Pipenv! edit                                     " The verbose flag doesn't matter

:Pipenv! sync dev=true                            " verbose=true, dev=false
:Pipenv! dev=true sync                            " Same as above

:Pipenv pre=true install ...                      " Installs prerelease packages

:Pipenv! python=3.13 install <PACKAGES>           " verbose=true, python=3.13

:Pipenv dev=true file=/path/to/file requirements  " verbose=false, dev=true, file=/path/to/file

Note that the remove subcommand only supports a bang (!) and treats it as "force" instead of "verbose":

Examples:

:Pipenv remove     " force=false, you will be prompted
:Pipenv! remove    " force=true, you will NOT be prompted

picker.nvim Integration

This plugin has a (rather rough) integration with wsdjeg/picker.nvim. If you have it installed you can run :Picker pipenv to use it.

API

Most of the API is publicly available on the main module pipenv.lua, which imports the utilities from core.lua.

The operations used by the :Pipenv user command are the following:

License

MIT