Locking and Synchronizing Dependencies

00:00 In the last lesson, we saw how to add main and group dependencies. In this lesson, I’ll show you how to lock and synchronize dependencies in your Poetry project.

00:11 These features are crucial for keeping your project’s environment consistent and reproducible, whether you’re working solo or collaborating within a team.

00:19 When you add or modify dependencies using Poetry’s command line interface, it automatically updates two important files. One is the pyproject.toml file. The pyproject.toml file lists the dependencies and version constraints, and then the poetry.lock file.

00:39 The poetry.lock file locks the exact version of those dependencies, ensuring that you are always working with the same versions across different environments.

00:50 Now, let’s say you manually add the dependency to your pyproject.toml file like this. You and I are going to manually include the requests library.

01:01 In this example, the asterisk means that you are allowing any version of the requests library. The library hasn’t been installed yet. You will need to run the poetry install command.

01:12 This poetry install command will then install the requests library and then update the poetry.lock file pinning down the exact version Poetry resolves.

01:23 I won’t run the poetry install just yet just to demonstrate something, but you can save the file after the manual entry using Ctrl+S or Command+S. Sometimes you might find that the poetry.lock file is out of sync with the pyproject. toml file. Poetry will warn you if this happens, and you can fix it by running poetry lock.

01:45 This command updates the poetry.lock file to reflect the current state of the pyproject.toml file without installing the dependencies. It resolves and locks all dependencies, including any sub-dependencies that your project might rely on.

02:01 If you want to lock new dependencies but don’t want to update existing ones, you can use the --no-update flag: poetry lock --no-update.

02:15 This tells Poetry to lock only the new dependencies and leave everything else as is. This is useful for when you want to avoid upgrading your existing packages.

02:25 Now, it’s important to understand that running poetry lock only locks the dependencies. It doesn’t actually install them. To confirm this, try importing one of the locked dependencies like the newly added requests without running poetry install, and you should get an error because the package hasn’t been installed yet.

02:42 For example, if we run poetry run python -c "import requests", this is just trying to execute the import requests within our Poetry virtual environment.

02:56 You should see a ModuleNotFoundError stating the module requests doesn’t exist in our environment. Note running poetry run is running the below Python script or command within our isolated virtual environment where it expects to have the requests library.

03:12 But now to install all locked dependencies, use the poetry install command.

03:19 This command reads from the poetry.lock file, and installs the exact versions pinned there.

03:26 I’ll now try to execute that command again and it should work fine. poetry run python -c for command and then import requests. It doesn’t do anything in particular, just importing the requests library, but it shows that the environment can now import and use that library to execute programs if needed.

03:47 The poetry.lock file is essential for keeping your environment consistent across different machines or when sharing your project with others.

03:56 But what if you’ve added extra packages in your virtual environments that aren’t in your pyproject. toml file or poetry.lock file?

04:04 To clean up those unnecessary packages, you would use the --sync command. To demonstrate this without editing the pyproject. toml file, you can install a package outside of your pyproject. toml or poetry.lock file.

04:19 To do this, you run the command poetry run python -m pip install httpie. Again, running poetry run will execute the past command in our virtual environment.

04:33 This should run and install httpie.

04:40 The httpie package indirectly brings about ten additional dependencies, which take up space and could potentially interfere with your project’s actual dependencies. Besides, external packages might sometimes create security holes if you don’t keep them up to date.

04:57 Now, to synchronize your virtual environments with the locked package pinned in the poetry.lock file, you can pass the optional --sync flag to the poetry install command like this: poetry install --sync.

05:14 You should see some packages being removed. This ensures that your virtual environment contains only the dependencies listed in the lock file, removing any extra or outdated packages, preventing potential conflicts caused by unnecessary or outdated dependencies.

05:31 Note on some best practices. If you’re working on an application, you should commit the poetry.lock file to a version control system like Git so that everyone working on the project uses the same packages as you.

05:44 By locking, synchronizing, and updating your dependencies with Poetry, you can maintain a stable, predictable environment for your project, ensuring it runs smoothly across different systems.

05:56 In the next lesson, I’ll show you how to update and upgrade your project’s dependencies using Poetry.