Skip to main content

​
Overview

Pion WebRTC v4.0.0 introduces several improvements and breaking changes. This guide will help you migrate your existing v3 applications to v4.
For detailed release notes, visit the v4.0.0 release page on GitHub.

​
Import Path Changes

The most significant change in v4 is the updated import path.

​
Update Import Statements

Change all imports from v3 to v4: 
// Old (v3)
import "github.com/pion/webrtc/v3"

// New (v4)
import "github.com/pion/webrtc/v4"

​
Update go.mod

Update your go.mod file to use v4: 
go get github.com/pion/webrtc/v4@latest
Make sure to enable Go Modules: 
export GO111MODULE=on

​
Dependency Updates

Pion WebRTC v4 updates several core dependencies. The following Pion packages have been updated:

ICE

Updated to github.com/pion/ice/v4

DTLS

Updated to github.com/pion/dtls/v3

SRTP

Updated to github.com/pion/srtp/v3

Transport

Updated to github.com/pion/transport/v4

​
API Changes

While Pion maintains API compatibility where possible, some changes may require updates to your code.

​
SettingEngine Updates

If you use the SettingEngine for custom configurations, review your settings as some methods may have updated signatures or behaviors. 
api := webrtc.NewAPI(
    webrtc.WithSettingEngine(settingEngine),
)

​
Error Handling

Error types may have changed. Review your error handling code: 
if err != nil {
    // Check error types if you're doing type assertions
    // Some error types may have been updated
}

​
Common Migration Issues

Make sure you’ve updated all import paths throughout your codebase:
# Find all v3 imports
grep -r "github.com/pion/webrtc/v3" .

# Replace with v4
find . -type f -name "*.go" -exec sed -i 's|github.com/pion/webrtc/v3|github.com/pion/webrtc/v4|g' {} +
Clean your module cache and update dependencies:
go clean -modcache
go mod tidy
go get -u ./...
If you’re using custom types or interfaces, ensure they’re compatible with v4:
  • Review the GoDoc for updated type definitions
  • Check that your custom implementations satisfy updated interfaces

​
Testing Your Migration

1

Update dependencies

Update all Pion packages and run go mod tidy
2

Fix compilation errors

Address any compilation errors from API changes
3

Run tests

Execute your test suite to ensure functionality
go test ./...
4

Integration testing

Test your application end-to-end with real WebRTC connections

​
Benefits of v4

Upgrading to v4 provides several advantages:
  • Improved Performance: Optimized packet processing and memory usage
  • Enhanced Stability: Bug fixes and stability improvements
  • Better Standards Compliance: Updated to latest WebRTC specifications
  • Dependency Updates: Latest versions of core Pion libraries
  • Go Version Support: Support for newer Go versions

​
Rollback Strategy

If you encounter issues during migration:
Always test migrations in a development environment before deploying to production.

​
Rolling Back

To rollback to v3: 
go get github.com/pion/webrtc/v3@latest
go mod tidy
Revert your import statements: 
find . -type f -name "*.go" -exec sed -i 's|github.com/pion/webrtc/v4|github.com/pion/webrtc/v3|g' {} +

​
Getting Help

If you need assistance with migration:

​
Next Steps

Examples

Explore updated examples using v4

API Reference

Browse the complete v4 API documentation

Troubleshooting

Common issues and solutions

Community

Get help from the Pion community

Build docs developers (and LLMs) love

Get started for freeTalk to us