docs/quick_start.md
This guide will help you get started with Pipenv quickly. It covers installation, basic usage, and common workflows to help you become productive with Pipenv in minutes.
# Install for the current user
$ pip install --user pipenv
Verify the installation:
$ pipenv --version
pipenv, version 2024.0.0
If the command isn't found, you may need to add the user site-packages bin directory to your PATH. See the Installation page for detailed instructions.
# Create a project directory
$ mkdir my_project
$ cd my_project
# Initialize a Pipenv environment
$ pipenv install
This creates a Pipfile in your project directory and a virtual environment for your project.
To use a specific Python version:
$ pipenv --python 3.10
# Install a package
$ pipenv install requests
# Install a package with version constraint
$ pipenv install "django>=4.0.0"
# Install a development dependency
$ pipenv install pytest --dev
# Show dependency graph
$ pipenv graph
# List installed packages
$ pipenv run pip list
# Uninstall a package
$ pipenv uninstall requests
# Activate the virtual environment
$ pipenv shell
# Now you're in the virtual environment
(my_project) $ python --version
Python 3.10.0
# Exit the environment
(my_project) $ exit
Without activating the environment:
# Run a Python script
$ pipenv run python app.py
# Run a command
$ pipenv run pytest
After installing packages, your Pipfile will look something like this:
[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"
[packages]
requests = "*"
django = ">=4.0.0"
[dev-packages]
pytest = "*"
[requires]
python_version = "3.10"
Generate a Pipfile.lock with exact versions and hashes:
$ pipenv lock
Install the exact versions specified in Pipfile.lock:
$ pipenv sync
This is useful for deployment or when you want to ensure exact package versions.
# Clone a repository
$ git clone https://github.com/example/project.git
$ cd project
# Install dependencies including development packages
$ pipenv install --dev
# Activate environment
$ pipenv shell
# Run tests
$ pytest
# Add a new dependency
$ pipenv install new-package
# Ensure Pipfile.lock is up-to-date
$ pipenv lock
# Install only production dependencies
$ pipenv install --deploy
# Scan for security vulnerabilities
$ pipenv scan
Create a .env file in your project directory:
# .env
DEBUG=True
API_KEY=your_secret_key
Pipenv automatically loads these variables when you use pipenv shell or pipenv run.
Access them in your Python code:
import os
debug = os.environ.get("DEBUG")
api_key = os.environ.get("API_KEY")
# Create project
$ mkdir django_project
$ cd django_project
# Initialize with Python 3.10
$ pipenv --python 3.10
# Install Django
$ pipenv install django
# Create Django project
$ pipenv run django-admin startproject mysite .
# Run development server
$ pipenv run python manage.py runserver
# Create project
$ mkdir data_analysis
$ cd data_analysis
# Install data science packages
$ pipenv install numpy pandas matplotlib jupyter
# Start Jupyter notebook
$ pipenv run jupyter notebook
# Create project
$ mkdir cli_tool
$ cd cli_tool
# Install dependencies
$ pipenv install click
# Create main.py
$ echo 'import click
@click.command()
@click.option("--name", default="World", help="Who to greet")
def hello(name):
"""Simple CLI tool that greets you."""
click.echo(f"Hello, {name}!")
if __name__ == "__main__":
hello()' > main.py
# Run the tool
$ pipenv run python main.py --name Friend
Hello, Friend!
# Show virtualenv location
$ pipenv --venv
/home/user/.local/share/virtualenvs/my_project-a1b2c3d4
# Show Python interpreter path
$ pipenv --py
/home/user/.local/share/virtualenvs/my_project-a1b2c3d4/bin/python
# Generate requirements.txt from Pipfile.lock
$ pipenv requirements > requirements.txt
# Set environment variable
$ export PIPENV_VENV_IN_PROJECT=1
# Install dependencies
$ pipenv install
# The virtualenv is now in .venv in your project directory
Add custom scripts to your Pipfile:
[scripts]
start = "python app.py"
test = "pytest"
lint = "flake8"
Run them with:
$ pipenv run start
$ pipenv run test
Now that you're familiar with the basics of Pipenv, you can explore more advanced topics:
For a complete reference of all Pipenv features, check out the full documentation.